API
Once you you have submitted a query to the Matching API, you will be returned back a requestId. The requestId will be needed to obtain your Matching results.
Once the Matching job has been completed, your matches will fall under three possible sections:
Person:
- Unique match: A single match with a score between 91 and 100
- Possible match: Multiple matches found, or a single match with a score between 61 and 90
- No match: No suitable match found
Organization:
- Unique match: A single match with a score between 90 and 100
- Possible match: Multiple matches found, or a single match with a score between 70 and 89
- No match: No suitable match found
Submit a request and obtain a requestID
Submit a statusRequest and wait until this returns a status of Matched Results Available
Get results (page if you have to)
(Optional) Find further information on your matches by using the Profile API
The API has a 6MB limitation per HTTP POST Request.
Available Data Points
For details on the available data points that can be used within your queries please navigate to the Documentation section within GraphiQL. Here you will find a list of the available data points, their definitions and data types. You can find the URL for GraphiQL on our URLs section.
Example Queries
This page lists a set of example queries which can be used as a starting point when working with the Matching API.
The ClientSuppliedId is a field required to use the Matching API. It is a unique alphanumeric string assigned to each input record, which allows you to correlate your record to the Altrata returned record.
Query
Submit queries to create a Matching job and be returned a requestId to retrieve the results.
Persons Match
The personsMatch query allows you to match records via name fileds & ID fields. The API accepts the following fields:
- clientSuppliedId
- firstName
- lastName
- middleName
- organizationName
- roleTitle
- age
- dateOfBirth
- workEmail
- personalEmail
- address1
- city1
- state1
- zipCode1
- country1
- familyMemberFirstName
- familyMemberMiddleName
- familyMemberLastName
- altrataId
- bxPersonId
- rsPersonId
- linkedinProfile
- wxPersonId
- briPersonId
- wePersonId
clientSuppliedId is a mandatory input along with at least one of the ID fields. Input schemes may be mixed, that is, within one request you may match on (for example) workEmail and linkedinProfile.
For the name matching clientSuppliedId, firstName, lastName are mandatory as well as either organizationName or zipcode1.
The following example matches Person on both Organization name & address data points.
mutation MyMutation {
personsMatch(
persons: [
{
clientSuppliedId: "32543",
firstName: "Iris",
lastName: "Deleon",
middleName: "Tiffany",
organizationName: "Ice Cream",
age: 87,
address1: "123 main st",
zipCode1: "18967",
city1: "Sim city"
}]
) {
... on RequestResponse {
requestId
}
... on GenericError {
__typename
genericErrorCode:code
errorMessage
correlationId
}
... on ValidationError {
__typename
validationErrorCode:code
correlationId
errorMessage
}
}
}
The following example matches Person on Organization name alone
mutation MyMutation {
personsMatch(
persons: [
{
clientSuppliedId: "32543",
firstName: "Iris",
lastName: "Deleon",
middleName: "Tiffany",
organizationName: "Ice Cream",
}]
) {
... on RequestResponse {
requestId
}
... on GenericError {
__typename
genericErrorCode:code
errorMessage
correlationId
}
... on ValidationError {
__typename
validationErrorCode:code
correlationId
errorMessage
}
}
}
The following example matches Person on address data points alone
mutation MyMutation {
personsMatch(
persons: [
{
clientSuppliedId: "32543",
firstName: "Iris",
lastName: "Deleon",
middleName: "Tiffany",
address1: "123 main st",
zipCode1: "18967",
city1: "Sim city",
country1: "US"
}]
) {
... on RequestResponse {
requestId
}
... on GenericError {
__typename
genericErrorCode:code
errorMessage
correlationId
}
... on ValidationError {
__typename
validationErrorCode:code
correlationId
errorMessage
}
}
}
If multiple ID schemes are passed within a single array element, and these result in multiple matches, the API will return these matches as discrete PossibleMatches.
The following example matches a single record by email. The email to match is [email protected] and the ID
mutation MyMutation {
personsMatch(persons: [
{
workEmail: "[email protected]",
clientSuppliedId: "1234"
}
]){
... on RequestResponse {
requestId
}
... on GenericError {
__typename
genericErrorcode:code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode:code
correlationId
errorMessage
}
}
}
The following example matches multiple records by email:
mutation MyMutation {
personsMatch( persons: [{
workEmail: "[email protected]",
clientSuppliedId: "1234"
},
{
workEmail: "[email protected]",
clientSuppliedId: "5678"
}
])
{
... on RequestResponse {
requestId
}
... on GenericError {
__typename
genericErrorcode:code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode:code
correlationId
errorMessage
}
}
}
The following example mixes multiple ID schemes:
mutation MyMutation {
personsMatch(
persons: [
{
workEmail: "[email protected]",
clientSuppliedId: "1234"
},
{
rsPersonId: "92346",
clientSuppliedId: "5678"
},
{
bxPersonId: "23947",
clientSuppliedId: "9873"
},
{
linkedinProfile: "https://www.linkedin.com/in/Iris-Deleon-618bba69/",
clientSuppliedId: "8653"
}]
) {
... on RequestResponse {
requestId
}
... on GenericError {
__typename
genericErrorcode:code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode:code
correlationId
errorMessage
}
}
}Organization Match
The organizationsMatch query allows you to match records via Organization names and ID fields. The API accepts the following fields:
- clientSuppliedId
- organizationName
- altrataId
- briOrganizationId
- bxOrganizationId
- rsOrganizationId
- tickerPrimary
- wxOrganizationId
Submit a set of Organization objects to be matched by name.
mutation MyMutation {
organizationsMatch(organizations: [
{
clientSuppliedId: "4080",
organizationName: "ice cream"
}
])
{
... on RequestResponse {
requestId
}
... on GenericError {
__typename
genericErrorcode:code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode:code
correlationId
errorMessage
}
}
}
Submit a set of Organization objects to be matched by name and Ids.
mutation MyMutation {
organizationsMatch(organizations: [
{
clientSuppliedId: "4080",
organizationName: "ice cream",
bxOrganizationId:"235245"
}
])
{
... on RequestResponse {
requestId
}
... on GenericError {
__typename
genericErrorcode:code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode:code
correlationId
errorMessage
}
}
}
Submit a set of Organization objects to be matched by Altrata IDs.
mutation MyMutation {
organizationsByIdMatch( organizations: [
{
bxOrganizationId: "4080",
briOrganizationId: null,
clientSuppliedId: "1234",
rsOrganizationId: "1127"
wxOrganizationId: null}
])
{
... on RequestResponse {
requestId
}
... on GenericError {
__typename
genericErrorcode:code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode:code
correlationId
errorMessage
}
}
}
Status
Check the current status of a Matching job along with providing the job summary details of the request when the results are available. The job is ready for results retrieval when the status is Matched Results Available.
Submit a simple query to fetch the staus of the Matching request.
query MyQuery {
requestStatus(input: {requestId: "matchapi_17266749000_Id_Oration_4a4f750b0ea977fa130cc05155346e581"}
) {
... on StatusDescription {
requestStatus
status
timestamp
}
... on GenericError {
__typename
genericErrorCode:code
correlationId
errorMessage
}
... on EntityNotFoundError {
__typename
entityNotFoundError:code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode:code
correlationId
errorMessage
}
}
}Submit a query to fetch the job summary details along with the expiry of the results
query MyQuery {
requestStatus(
input: {requestId: "matchapi_17266749000_Id_Oration_4a4f750b0ea977fa130cc05155346e581"}
) {
... on StatusDescription {
requestStatus
status
timestamp
jobSummary {
noMatchCount
possibleMatchCount
recordsSubmittedCount
uniqueMatchCount
}
expiresOn
}
... on GenericError {
__typename
genericErrorCode: code
correlationId
errorMessage
}
... on EntityNotFoundError {
__typename
entityNotFoundError: code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode: code
correlationId
errorMessage
}
}
}With allRequestStatuses query, the user will be able to see the status of all the matching requests they have submitted upto 30 days.
query MyQuery {
allRequestStatuses {
... on StatusRequestsForUserResponse {
__typename
data {
expiresOn
requestId
requestStatus
status
timestamp
jobSummary {
noMatchCount
possibleMatchCount
recordsSubmittedCount
uniqueMatchCount
}
}
}
... on GenericError {
__typename
genericErrorCode: code
correlationId
errorMessage
}
... on EntityNotFoundError {
__typename
entityNotFoundError: code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode: code
correlationId
errorMessage
}
}
}You must change the requestId to be the requestId which was returned to you previously.
Results
Retrieve results for a Matching job. Three queries will be required:
personUniqueMatches to obtain all Unique Matches
personPossibleMatches to obtain all Possible Matches
personNoMatches to obtain all No Matches
Once results are obtained, you may wish to connect to the Profile API to obtain further information on your matched results
Each response may be paginated. See Paging to learn how to page over the results.
Person Unique Matches
Retrieve paginated unique matches for a given Matching job.
query MyQuery {
personUniqueMatches(
input: {requestId: "TestingRequestId"}
pageInfo: {first: 5, after: "5"}
) {
... on PersonMatchesResponse {
__typename
data
{
clientSuppliedId
matches {
matchScore
firstName
lastName
organizationName
roleTitle
address1
city1
state1
zipCode1
country1
altrataId
briPersonId
bxPersonId
wePersonId
wxPersonId
}
}
pageInfo {
endCursor
}
}
... on GenericError {
__typename
genericErrorCode: code
correlationId
errorMessage
}
... on EntityNotFoundError {
__typename
entityNotFoundError: code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode: code
correlationId
errorMessage
}
}
}Person Possible Matches
Retrieve paginated possible matches for a given Matching job.
query MyQuery {
personPossibleMatches(
input: {requestId: "TestingRequestId"}
pageInfo: {after: "5", first: 5}
) {
... on PersonMatchesResponse {
__typename
data
{
clientSuppliedId
matches {
matchScore
firstName
lastName
clientFirstName
clientLastName
organizationName
clientOrganizationName
roleTitle
clientRoleTitle
address1
city1
state1
zipCode1
country1
clientAddress1
clientCity1
clientState1
clientZipCode1
clientCountry1
altrataId
briPersonId
bxPersonId
rsPersonId
wePersonId
wxPersonId
}
}
pageInfo {
endCursor
}
}
... on GenericError {
__typename
genericErrorCode: code
correlationId
errorMessage
}
... on EntityNotFoundError {
__typename
entityNotFoundError: code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode: code
correlationId
errorMessage
}
}
}Address data will be populated in the response only when the address data was present in the input data.
Person No Match
Retrieve paginated results that were not matched.
query MyQuery {
personNoMatches(
input: {requestId: "TestingRequestId"},
pageInfo: {after: "5", first: 5}
) {
... on PersonMatchesResponse {
data {
clientSuppliedId
}
pageInfo {
endCursor
}
}
... on GenericError {
__typename
genericErrorCode: code
correlationId
errorMessage
}
... on EntityNotFoundError {
__typename
entityNotFoundError: code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode: code
correlationId
errorMessage
}
}
}Organization Unique Matches
Retrieve paginated unique matches for a given Matching job.
query MyQuery {
organizationUniqueMatches(
input: {requestId: "TestingRequestId"}
pageInfo: {after: "5", first: 5}
) {
... on OrganizationMatchesResponse {
__typename
data {
clientSuppliedId
matches {
matchScore
organizationName
altrataId
briOrganizationId
bxOrganizationId
rsOrganizationId
wxOrganizationId
}
}
pageInfo {
endCursor
}
}
... on GenericError {
__typename
genericErrorCode: code
correlationId
errorMessage
}
... on EntityNotFoundError {
__typename
entityNotFoundError: code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode: code
correlationId
errorMessage
}
}
}Organization Possible Matches
Retrieve paginated possible matches for a given Matching job.
query MyQuery {
organizationPossibleMatches(
input: {requestId: "TestingRequestId"}
pageInfo: {after: "5", first: 5}
) {
... on OrganizationMatchesResponse {
data {
clientSuppliedId
matches {
altrataId
matchScore
organizationName
rsOrganizationId
briOrganizationId
bxOrganizationId
wxOrganizationId
}
}
pageInfo {
endCursor
}
}
... on GenericError {
__typename
genericErrorCode: code
correlationId
errorMessage
}
... on EntityNotFoundError {
__typename
entityNotFoundError: code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode: code
correlationId
errorMessage
}
}
}Organization No Match
Retrieve paginated results that we were unable to match.
query MyQuery {
organizationNoMatches(input: {requestId: "ExampleID"}, pageInfo: {after: "", first: 10}
) {
... on OrganizationMatchesResponse {
__typename
data {
clientSuppliedId
}
pageInfo {
endCursor
}
}
... on GenericError {
__typename
genericErrorCode: code
correlationId
errorMessage
}
... on EntityNotFoundError {
__typename
entityNotFoundError: code
correlationId
errorMessage
}
... on ValidationError {
__typename
validationErrorCode: code
correlationId
errorMessage
}
}
}