---
title: API
slug: api
docTags: 
createdAt: 2024-04-29T10:10:50.123Z
---

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 92 and 100
- **Possible match:** Multiple matches found, or a single match with a score between 63 and 91
- **No match: **No suitable match found

::::WorkflowBlock
:::WorkflowBlockItem
Submit a request and obtain a requestID
:::

:::WorkflowBlockItem
Submit a `statusRequest` and wait until this returns a status of `Matched Results Available`
:::

:::WorkflowBlockItem
Get results (page if you have to)
:::

:::WorkflowBlockItem
(Optional) Find further information on your matches by using the [Profile API](docId\:Jp__Be2Ni-Ds_C9CwHoPT)
:::
::::



:::hint{type="warning"}
**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](docId:3rGzMF5UH3ep0bh4snVm0) 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` or `address1 & city1`

The following example matches Person on both Organization name & address data points. 

```graphql
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

```graphql
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

```graphql
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
    }
  }
}


 
```

:::hint{type="warning"}
I**f 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 example\@example.org and the ID 

```graphql
mutation MyMutation {
  personsMatch(persons: [
    {
      workEmail: "example@example.org",
      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:

```graphql
mutation MyMutation {
  personsMatch( persons: [{
      workEmail: "example@example.org",
      clientSuppliedId: "1234"
    },
    {
      workEmail: "example2@example.org",
      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:

```graphql
mutation MyMutation {
  personsMatch(
    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 {
      __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
- headOfficeCountry
- wxOrganizationId

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
      genericErrorcode:code
      correlationId
      errorMessage
    }
    ... on ValidationError {
      __typename
      validationErrorCode:code
      correlationId
      errorMessage
    }
  }
}
    
  
```

Submit a set of Organization objects to be matched by name and Ids.

```graphql

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.

```graphql
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.

```graphql
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

```graphql
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.

```graphql
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
    }
  }
}
```

:::hint{type="danger"}
**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:

::::WorkflowBlock
:::WorkflowBlockItem
`personUniqueMatches` to obtain all Unique Matches
:::

:::WorkflowBlockItem
`personPossibleMatches` to obtain all Possible Matches
:::

:::WorkflowBlockItem
`personNoMatches` to obtain all No Matches
:::

:::WorkflowBlockItem
Once results are obtained, you may wish to connect to the [Profile API](docId\:Jp__Be2Ni-Ds_C9CwHoPT) to obtain further information on your matched results
:::
::::

Each response may be paginated. See [Paging](docId\:Yxho373jhbo0MWUYyPZ5G) to learn how to page over the results.

### Person Unique Matches

Retrieve paginated unique matches for a given Matching job.

```graphql
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.

```graphql
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
    }
  }
}
```

:::hint{type="warning"}
**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.

```graphql
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.

```graphql
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.

```graphql
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.

```graphql
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
    }
  }
}
```