Example queries

17min
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
Submit a set of Person objects to be matched by name and organization name.
clientSuppliedId, firstName, lastNameand organizationNameare mandatory input fields.
GraphQL
mutation MyMutation {
  personsMatch(
     persons: [
      {
        clientSuppliedId: "32543", 
        firstName: "Iris",
        lastName: "Deleon", 
        middleName: "Tiffany", 
        organizationName: "Ice Cream", 
        roleTitle: "Chief product officer"}]
  ) {
    ... on RequestResponse {
      requestId
    }
    ... on GenericError {
      __typename
      correlationId
      errorCode
      errorMessage
    }
  }
}


 
mutation MyMutation {
  personsMatch(
     persons: [
      {
        clientSuppliedId: "32543", 
        firstName: "Iris",
        lastName: "Deleon", 
        middleName: "Tiffany", 
        organizationName: "Ice Cream", 
        roleTitle: "Chief product officer"}]
  ) {
    ... on RequestResponse {
      requestId
    }
    ... on GenericError {
      __typename
      correlationId
      errorCode
      errorMessage
    }
  }
}


 
﻿
Person by ID Match
The personByIdMatch query allows you to match records via unique ids. The API accepts the following id schemes:
altrataId
clientSuppliedId
bxPersonId
rsPersonId
workEmail
linkedinProfile
wxPersonId
briPersonId
wePersonId
clientSuppliedId is a mandatory input along with at least one of the fields. Input schemes may be mixed, that is, within one request you may match on (for example) workEmail and linkedinProfile.
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 
GraphQL
mutation MyMutation {
  personsByIdMatch(persons: [{
      workEmail: "[email protected]",
      clientSuppliedId: "1234"}]) {
    ... on RequestResponse {
      requestId
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}

mutation MyMutation {
  personsByIdMatch(persons: [{
      workEmail: "example@example.org",
      clientSuppliedId: "1234"}]) {
    ... on RequestResponse {
      requestId
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
﻿
The following example matches multiple records by email:
GraphQL
mutation MyMutation {
  personsByIdMatch( persons: [{
      workEmail: "[email protected]",
      clientSuppliedId: "1234"
    },
    {
      workEmail: "[email protected]",
      clientSuppliedId: "5678"
    }]) {
    ... on RequestResponse {
      requestId
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
   
mutation MyMutation {
  personsByIdMatch( persons: [{
      workEmail: "example@example.org",
      clientSuppliedId: "1234"
    },
    {
      workEmail: "example2@example.org",
      clientSuppliedId: "5678"
    }]) {
    ... on RequestResponse {
      requestId
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
   
﻿
The following example mixes multiple ID schemes:
GraphQL
mutation MyMutation {
  personsByIdMatch(
    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 {
      correlationId
      errorCode
      errorMessage
    }
    }
}
mutation MyMutation {
  personsByIdMatch(
    persons: [{
      workEmail: "example@example.org",
      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 {
      correlationId
      errorCode
      errorMessage
    }
    }
}
﻿
Organization Match
Submit a set of Organization objects to be matched by name.
GraphQL

mutation MyMutation {
  organizationsMatch(organizations: [
      {
        clientSuppliedId: "4080",
     		organizationName: "ice cream"
      }
    ]) {
    ... on RequestResponse {
      requestId
    }
    ... on GenericError {
      __typename
      correlationId
      errorCode
      errorMessage
    }
  }
}
    
  

mutation MyMutation {
  organizationsMatch(organizations: [
      {
        clientSuppliedId: "4080",
     		organizationName: "ice cream"
      }
    ]) {
    ... on RequestResponse {
      requestId
    }
    ... on GenericError {
      __typename
      correlationId
      errorCode
      errorMessage
    }
  }
}
    
  
﻿
Organization by ID Match
Submit a set of Organization objects to be matched by Altrata IDs.
The organizationByIdMatch query allows you to match records via unique ids. The API accepts the following id schemes:
altrataId
clientSuppliedId
bxOrganizationId
rsOrganizationId
workEmail
linkedinProfile
wxOrganizationId
briOrganizationId
clientSuppliedId is a mandatory input along with at least one of the fields.
GraphQL
mutation MyMutation {
  organizationsByIdMatch( organizations: [
      {
        bxOrganizationId: "4080", 
        briOrganizationId: null, 
        clientSuppliedId: "1234", 
        rsOrganizationId: "1127", 
        tickerPrimary: "ICE.C", 
        wxOrganizationId: null}
    ]) {
    ... on RequestResponse {
      requestId
    }
    ... on GenericError {
      __typename
      correlationId
      errorCode
      errorMessage
    }
  }
}
   
  
mutation MyMutation {
  organizationsByIdMatch( organizations: [
      {
        bxOrganizationId: "4080", 
        briOrganizationId: null, 
        clientSuppliedId: "1234", 
        rsOrganizationId: "1127", 
        tickerPrimary: "ICE.C", 
        wxOrganizationId: null}
    ]) {
    ... on RequestResponse {
      requestId
    }
    ... on GenericError {
      __typename
      correlationId
      errorCode
      errorMessage
    }
  }
}
   
  
﻿
Status
Check the current status of a Matching job. The job is ready for results retrieval when the status is Matched Results Available.
GraphQL
query MyQuery {
  requestStatus(
    input: {requestId: "matchapi_17266749000_Id_Oration_4a4f750b0ea977fa130cc05155346e581"}
  ) {
    ... on StatusDescription {
      description
      status
      timestamp
    }
    ... on GenericError {
      __typename
      errorMessage
    }
  }
}
query MyQuery {
  requestStatus(
    input: {requestId: "matchapi_17266749000_Id_Oration_4a4f750b0ea977fa130cc05155346e581"}
  ) {
    ... on StatusDescription {
      description
      status
      timestamp
    }
    ... on GenericError {
      __typename
      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:
1
personUniqueMatches to obtain all Unique Matches
2
personPossibleMatches to obtain all Possible Matches
3
personNoMatches to obtain all No Matches
4
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. Each of the above queries contains a jobSummary object which will provide the overall match statistics of your job.
Person Unique Matches
Retrieve paginated unique matches for a given Matching job.
GraphQL
query MyQuery {
  personUniqueMatches(input: {requestId: "ExampleID"}, pageInfo: {first: 10, after: ""}) {
    ... on PersonMatchesResponse {
      data {
        clientSuppliedId
        matches {
          altrataId
          matchScore
          firstName
          lastName
          organizationName
        }
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
query MyQuery {
  personUniqueMatches(input: {requestId: "ExampleID"}, pageInfo: {first: 10, after: ""}) {
    ... on PersonMatchesResponse {
      data {
        clientSuppliedId
        matches {
          altrataId
          matchScore
          firstName
          lastName
          organizationName
        }
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
﻿
Person Possible Matches
Retrieve paginated possible matches for a given Matching job.
GraphQL
query MyQuery {
  personPossibleMatches(input: {requestId: "ExampleID"}, pageInfo: {after: "", first: 10}) {
    ... on PersonMatchesResponse {
      __typename
      data {
        clientSuppliedId
        matches {
          altrataId
          matchScore
          firstName
          lastName
          organizationName
          roleTitle
        }
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      __typename
      correlationId
      errorCode
      errorMessage
    }
  }
}
query MyQuery {
  personPossibleMatches(input: {requestId: "ExampleID"}, pageInfo: {after: "", first: 10}) {
    ... on PersonMatchesResponse {
      __typename
      data {
        clientSuppliedId
        matches {
          altrataId
          matchScore
          firstName
          lastName
          organizationName
          roleTitle
        }
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      __typename
      correlationId
      errorCode
      errorMessage
    }
  }
}
﻿
Person No Match
Retrieve paginated results that were not matched.
GraphQL
query MyQuery {
  personNoMatches(input: {requestId: "ExampleID"}, pageInfo: {after: "", first: 10}) {
    ... on PersonMatchesResponse {
        data {
        clientSuppliedId
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
query MyQuery {
  personNoMatches(input: {requestId: "ExampleID"}, pageInfo: {after: "", first: 10}) {
    ... on PersonMatchesResponse {
        data {
        clientSuppliedId
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
﻿
Organization Unique Matches
Retrieve paginated unique matches for a given Matching job.
GraphQL
query MyQuery {
  organizationUniqueMatches(
    input: {requestId: "ExampleID"}
    pageInfo: {after: "", first: 10}
  ) {
    ... on OrganizationMatchesResponse {
       data {
        clientSuppliedId
        matches {
          altrataId
          matchScore
          organizationName
          organizationType
        }
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
query MyQuery {
  organizationUniqueMatches(
    input: {requestId: "ExampleID"}
    pageInfo: {after: "", first: 10}
  ) {
    ... on OrganizationMatchesResponse {
       data {
        clientSuppliedId
        matches {
          altrataId
          matchScore
          organizationName
          organizationType
        }
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
﻿
Organization Possible Matches
Retrieve paginated possible matches for a given Matching job.
GraphQL
query MyQuery {
  organizationPossibleMatches(
    input: {requestId: "ExampleID"}
    pageInfo: {after: "", first: 10}
  ) {
    ... on OrganizationMatchesResponse {
      data {
        clientSuppliedId
        matches {
          altrataId
          matchScore
          organizationName
          organizationType
        }
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
query MyQuery {
  organizationPossibleMatches(
    input: {requestId: "ExampleID"}
    pageInfo: {after: "", first: 10}
  ) {
    ... on OrganizationMatchesResponse {
      data {
        clientSuppliedId
        matches {
          altrataId
          matchScore
          organizationName
          organizationType
        }
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
﻿
Organization No Match
Retrieve paginated results that we were unable to match.
GraphQL
query MyQuery {
  organizationNoMatches(input: {requestId: "ExampleID"}, pageInfo: {after: "", first: 10}) {
    ... on OrganizationMatchesResponse {
      __typename
      data {
        clientSuppliedId
        matches {
          altrataId
          matchScore
          organizationName
          organizationType
        }
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
query MyQuery {
  organizationNoMatches(input: {requestId: "ExampleID"}, pageInfo: {after: "", first: 10}) {
    ... on OrganizationMatchesResponse {
      __typename
      data {
        clientSuppliedId
        matches {
          altrataId
          matchScore
          organizationName
          organizationType
        }
      }
      pageInfo {
        endCursor
      }
    }
    ... on GenericError {
      correlationId
      errorCode
      errorMessage
    }
  }
}
﻿
﻿
Updated 07 Oct 2024
Did this page help you?
Getting Started
Salesforce App