External match API

Use this API to get information on potential matches in a tenant for entities that are added to the tenant from an external file.

Use the external match API to match records stored externally in a file with entities in a Reltio tenant. To use this API, you must provide an input file that contains the records to be matched. This API is counted towards your monthly API quota based on the number of records in the input file. For example, if you have 10,000 records in the input file the platform will report 10,000 API calls towards the monthly quota. The input file can be stored in AWS S3 storage, GCP storage, or Azure blob storage.

The following sections provide information on the request API, request parameters, body parameters, and the input and output file formats for any storage type. Reltio recommends that you use parameters for either the GCP or AWS S3 storage at a time. For information on the parameters for specific storage types, see topics External match API - AWS, External match API - GCP, and External match API - Azure.

Note:

Entities must be represented as a JSON array in an AWS S3, GCP, or Azure Blob file.
Each entity JSON should be on a separate line of an AWS S3, GCP, or Azure Blob file.

Request

Admin role is required:

POST {ApplicationURL}/externalMatch

Tenant Role is required:

POST {ApplicationURL}/api/{tenantId}/externalMatch

Request Parameters

The following request parameters are used:


Parameters	Required	Description
`tenantId`	No	ID of the tenant to reindex potential matches.
`entityType`	No	Entity type to filter and match from the entire set of entities represented in an external file.
`fileFormat`	No	The format of the Output file: CSV— CSV format JSON — Multi-line JSON. Using a single input line results in multiple output lines. JSON_v2 — Single line JSON. Using a single input line results into single output line. Default file format: JSON. Constants aren't case sensitive.
`distributed`	No	Specifies whether the task is distributed or not. Default is `false`.
`distributedTasksPartsCount`	No	Defines the number of distributed tasks to be created. Default is 2.
`path`	Yes	Determines the path to a source file in a bucket (including folders, if necessary).
`pathOut`	Yes	Determines the path where the output result file will be created in a bucket (including folders, if necessary).
`fileEncoding`	No	Defines the source and result file encoding. Default is UTF-8.
`rowsLimit`	No	Defines the number of rows (entities) to be processed from the source.
`skiprowsCount`	No	Defines the number of rows (entities) to be skipped from the source file.
`distributedTaskIndex`	No	Defines task index to start only. If not defined, all created tasks will be started automatically.
`emails`	No	Defines a comma-separated list of emails to which a notification of completion will be sent.
`maxPotentialMatchesPerChunk`	No	External match goes through entities by chunk (10 entities), each chunk has a limitation for the maximum of potential matches found by chunk. Default value is 200.
`rules`	No	Defines a comma separated set of match group URIs which must take part in the matching process. All other match groups will be ignored if this parameter is defined. Sample format: `rules=configuration/entityTypes/HCP/matchGroups/MatchByMiddleName,configuration/entityTypes/HCP/matchGroups/MatchByMiddleNameAndLastName`
`cleanse`	No	If set to true, the API enriches the entities with the cleansed values for attributes. The cleansed entities are then matched with the entities in the tenant. The default value is false.
`resolveLookups`	No	If set to `true`, then lookups are resolved for entities in the input file. The default value is `false`.

The following body parameters are used:


Parameters	Required	Description
`selectAttributes`	No	Array of string values that allow you to select attributes to be included in the output file. Examples `[ "configuration/entityTypes/HCP/attributes/FirstName", "configuration/entityTypes/HCP/attributes/Identifiers/attributes/Type" ]`
`options`	No	This is comma-separated list of different options that affect the relation's JSON content in the response and the override process. The following options are available: `ovOnly` - returns only attribute values that have the `ov=true` flag. `nonOvOnly` - returns only attribute values that have the `ov=false` flag. If you have a nested or reference attribute value which has `ov=true`, but has sub-attributes with `ov=false`, then these subattributes won't appear in the response

Input file format

The input file can be in the following format:

Note: Each entity must occupy only one row of the input file.

{"uri":"entities/aaa","type":"configuration/entityTypes/HCP","attributes":{"Name":[{"value":"NAME_DDD"}],"FirstName":[{"value":"FIRST_GGG"}],"LastName":[{"value":"LAST_GGG"}],"MiddleName":[{"value":"VAN"}],"Employment":[{"value":{"Title":[{"value":"TITLE_GGG"},{"value":"TITLE_GGG"}],"Summary":[{"value":"SUMMARY_GGG"}]}}],"Address":[{"value":{"City":[{"value":"CITY_GGG"}]}}],"Identifiers":[{"value":{"Type":[{"value":"TYPE2"}],"ID":[{"value":"ID1"}]}}]},"crosswalks":[{"value":"CROSSWALK_aaa","sourceTable":"SOURCE_TABLE_GGG","type":"configuration/sources/LNKD"}]},
{"uri":"entities/bbb","type":"configuration/entityTypes/HCP","attributes":{"Name":[{"value":"NAME_HHH"}],"FirstName":[{"value":"FIRST_HHH"}],"LastName":[{"value":"LAST_HHH"}],"MiddleName":[{"value":"VAN"}],"Employment":[{"value":{"Title":[{"value":"TITLE_HHH"},{"value":"TITLE_HHH"}],"Summary":[{"value":"SUMMARY_HHH"}]}}],"Address":[{"value":{"City":[{"value":"CITY_HHH"}]}}],"Identifiers":[{"value":{"Type":[{"value":"TYPE2"}],"ID":[{"value":"ID1"}]}}]},"crosswalks":[{"value":"CROSSWALK_bbb","sourceTable":"SOURCE_TABLE_HHH","type":"configuration/sources/LNKD"}]}

The input file can also be in the following format:

[
{"uri":"entities/aaa","type":"configuration/entityTypes/HCP","attributes":{"Name":[{"value":"NAME_DDD"}],"FirstName":[{"value":"FIRST_GGG"}],"LastName":[{"value":"LAST_GGG"}],"MiddleName":[{"value":"VAN"}],"Employment":[{"value":{"Title":[{"value":"TITLE_GGG"},{"value":"TITLE_GGG"}],"Summary":[{"value":"SUMMARY_GGG"}]}}],"Address":[{"value":{"City":[{"value":"CITY_GGG"}]}}],"Identifiers":[{"value":{"Type":[{"value":"TYPE2"}],"ID":[{"value":"ID1"}]}}]},"crosswalks":[{"value":"CROSSWALK_aaa","sourceTable":"SOURCE_TABLE_GGG","type":"configuration/sources/LNKD"}]},
{"uri":"entities/bbb","type":"configuration/entityTypes/HCP","attributes":{"Name":[{"value":"NAME_HHH"}],"FirstName":[{"value":"FIRST_HHH"}],"LastName":[{"value":"LAST_HHH"}],"MiddleName":[{"value":"VAN"}],"Employment":[{"value":{"Title":[{"value":"TITLE_HHH"},{"value":"TITLE_HHH"}],"Summary":[{"value":"SUMMARY_HHH"}]}}],"Address":[{"value":{"City":[{"value":"CITY_HHH"}]}}],"Identifiers":[{"value":{"Type":[{"value":"TYPE2"}],"ID":[{"value":"ID1"}]}}]},"crosswalks":[{"value":"CROSSWALK_bbb","sourceTable":"SOURCE_TABLE_HHH","type":"configuration/sources/LNKD"}]}
]

Output file format

You can use the JSON format for the output file that allows you to select attributes of the matched Reltio entity to be included in the output file. Identify records from the input file that have matched or non-matched entities without having to join the input and output file. The output file format includes the following fields:


Field	Description
`inputRecordID`	The URI of the record from the file.
`inputRecordAttributes`	The facet of selected attributes of the record from the file.
`matchedEntities`	An array of matched entities and each entity has a field structure explained in the following table.

Table 1. Field structure of the matched entity
Field	Description
`uri`	URI of the matched entity.
`entityTypeUri`	Entity Type of the matched entity.
`matchRuleUri`	Match rule URI of the matched entity.
`matchRuleType`	Type of the match rule (values: automatic, suspect, relevance_based).
`matchRuleName`	Match rule label of the matched entity.
`matchRuleAction`	Match Rule Action (Auto_Merge, Potential_Match, Not_A_Match).
`entitymatchScore`	Match score of the matched entity.
`matchRelevance`	Relevance score of the matched entity.
`attributes`	A facet of selected attributes of the matched entity.
`crosswalks`	Crosswalks of the matched entity.

External match job statistics

In addition to the new file format, the external match API is enhanced to provide statistics about the external job. These statistics provide more details about the external match job to help you better understand the results of matching. The following statistics are used in the output file:


Name	Description
`totalNumberOfMatches`	Count of line items that were matched to at least one profile in the Reltio tenant.
`totalNumberOfNonMatches`	Count of line items that weren't matched to any profile in the Reltio Tenant.
`totalNumberOfRecordParseErrors`	Count of line items that weren't read due to a parsing error (bad formatting, null values, and so on.)
`totalNumberOfAutoMerges`	Count of line items that were merged automatically because the match rule type was automatic or the relevance-based action was auto_merge.
`totalNumberOfPotentialMatches`	Count of line items that are marked as potential matches because the match rule type is suspect or the relevance-based action was potential_match.
`totalNumberOfNotAMatches`	Count of line items that are marked as not a match because of not a match exclusion or the relevance-based action is neither auto_merge nor potential_match.
`totalNumberOfCleanseError`	Count of line items for which cleanse errors were reported.

The following reports display the new file format:

CSV external match report

Request:

http://localhost:8080/reltio/api/Merill/externalMatch?fileFormat=csv&entityType=HCP

Body:

{
"options": "ovOnly",
"selectAttributes":
[ "configuration/entityTypes/HCP/attributes/FirstName", 
"configuration/entityTypes/HCP/attributes/Identifiers/attributes/Type" ]
}

Response:

The executed task body contains public counters available for use. 
{
    "id": "4941e021-862e-436b-98c4-2d188106dda6",
    ...
    "currentState": {
        "totalNumberOfSkippedRecords": 0,
        "numberOfFailedToPublishEvents": 0,
        "totalRecordInInputFile": 2,
        "totalNumberOfNotAMatches": 0,
        "totalNumberOfPotentialMatches": 3,
        "entityType": "configuration/entityTypes/HCP",
        "totalNumberOfRecordParseErrors": 0,
        "totalNumberOfAutoMerges": 0,
        "lastHourThroughput": 0,
        "numberOfProcessedObjects": 2,
        "exportUrl": "rp31694externalmatch/inputData.json",
        "totalNumberOfMatches": 1,
        "totalNumberOfNonMatches": 1,
        "status": "Completed"
    }
}

Output:

uriSource,matchRule,ruleType,urisMatched
entities/ddd,configuration/entityTypes/HCP/matchGroups/MatchByMiddleName,suspect,0001BWT;0000ZA9;0000lwv
entities/iii,,

Single-line JSON external match report

Request:

http://localhost:8080/reltio/api/Merill/externalMatch?
s3Path=inputData.json&s3Bucket=rp31694externalmatch&s3Region=us-east-
1&awsAccessKey=ACCESSKEY&awsSecretKey=SECRETKEY&s3PathOut=jobResult.json&entityType=HCP&tenantId=Merill
&fileFormat=json&rowsLimit=3&skipRowsCount=2&distributed=false

Response:

The executed task body contains public counters available for use. 
{
    "id": "f7d0af62-79ff-4b09-9b41-bcbfce7e9aa6",
    ...
    "currentState": {
        "totalNumberOfSkippedRecords": 0,
        "numberOfFailedToPublishEvents": 0,
        "totalRecordInInputFile": 2,
        "totalNumberOfNotAMatches": 0,
        "totalNumberOfPotentialMatches": 3,
        "entityType": "configuration/entityTypes/HCP",
        "totalNumberOfRecordParseErrors": 0,
        "totalNumberOfAutoMerges": 0,
        "lastHourThroughput": 0,
        "numberOfProcessedObjects": 2,
        "exportUrl": "rp31694externalmatch/inputData.json",
        "totalNumberOfMatches": 1,
        "totalNumberOfNonMatches": 1,
        "status": "Completed"
    }
}

Output:

{"uriSource":"entities/ddd","matchRule":"configuration/entityTypes/HCP/matchGroups/MatchByMiddleName","ruleType":"suspect","urisMatched":["0001BWT","0000ZA9","0000lwv"]}
{"uriSource":"entities/iii","matchRule":"","ruleType":"","urisMatched":[]}

Each line in the output is a JSON that if indented appears as follows:

{
  "uriSource": "entities/ddd",
  "matchRule": "configuration/entityTypes/HCP/matchGroups/MatchByMiddleName",
  "ruleType": "suspect",
  "urisMatched": [
    "0001BWT",
    "0000ZA9",
    "0000lwv"
  ]
}

Multi-line JSON external match report

Request:

http://localhost:8080/reltio/api/Merill/externalMatch?
s3Path=inputData.json&s3Bucket=rp31694externalmatch&s3Region=us-east-
1&awsAccessKey=ACCESSKEY&awsSecretKey=SECRETKEY&s3PathOut=jobResult.json&entityType=HCP&tenantId=Merill
&fileFormat=json_v2&rowsLimit=3&skipRowsCount=2&distributed=false

Response:

The executed task body contains public counters available for use.

{
    "id": "90cc292a-0171-40f0-9819-6f2d16cf40ba",
    ...
    "currentState": {
        "totalNumberOfSkippedRecords": 0,
        "numberOfFailedToPublishEvents": 0,
        "totalRecordInInputFile": 2,
        "totalNumberOfNotAMatches": 0,
        "totalNumberOfPotentialMatches": 3,
        "entityType": "configuration/entityTypes/HCP",
        "totalNumberOfRecordParseErrors": 0,
        "totalNumberOfAutoMerges": 0,
        "lastHourThroughput": 0,
        "numberOfProcessedObjects": 2,
        "exportUrl": "rp31694externalmatch/inputData.json",
        "totalNumberOfMatches": 1,
        "totalNumberOfNonMatches": 1,
        "status": "Completed"
    }
}

Output:

{"inputRecordId":"entities/ddd","inputRecordAttributes":{"FirstName":[{"value":"FIRST_GGG"}],"Identifiers":[{"value":{"Type":[{"value":"TYPE2"}]}}]},"matchedEntities":[{"uri":"entities/0001BWT","entityTypeUri":"configuration/entityTypes/HCP","matchRuleUri":"configuration/entityTypes/HCP/matchGroups/MatchByMiddleName","matchRuleName":"Match by MiddleName","matchRuleType":"suspect","matchRuleAction":"POTENTIAL_MATCH","entityMatchScore":0,"attributes":{"FirstName":[{"value":"GGG1"}],"Identifiers":[{"value":{"Type":[{"value":"TYPE2"}]}}]},"crosswalks":[{"value":"cv51hpa","type":"Reltio"}]},{"uri":"entities/0000ZA9","entityTypeUri":"configuration/entityTypes/HCP","matchRuleUri":"configuration/entityTypes/HCP/matchGroups/MatchByMiddleName","matchRuleName":"Match by MiddleName","matchRuleType":"suspect","matchRuleAction":"POTENTIAL_MATCH","entityMatchScore":0,"attributes":{"FirstName":[{"value":"GGG2"}],"Identifiers":[{"value":{"Type":[{"value":"TYPE2"}]}}]},"crosswalks":[{"value":"zaj3hpj","type":"Reltio"}]},{"uri":"entities/0000lwv","entityTypeUri":"configuration/entityTypes/HCP","matchRuleUri":"configuration/entityTypes/HCP/matchGroups/MatchByMiddleName","matchRuleName":"Match by MiddleName","matchRuleType":"suspect","matchRuleAction":"POTENTIAL_MATCH","entityMatchScore":0,"attributes":{"FirstName":[{"value":"GGG3"}],"Identifiers":[{"value":{"Type":[{"value":"TYPE2"}]}}]},"crosswalks":[{"value":"qcre1mn","type":"Reltio"}]}]}
{"inputRecordId":"entities/iii","matchedEntities":[]}

Each line in the output is an entity that if indented appears as follows:

{
  "inputRecordID": "entities/ddd",
  "inputRecordAttributes": {
    "FirstName": [
      {
        "value": "FIRST_GGG"
      }
    ],
    "Identifiers": [
      {
        "value": {
          "Type": [
            {
              "value": "TYPE2"
            }
          ]
        }
      }
    ]
  },
  "matchedEntities": [
    {
      "uri": "entities/0001BWT",
      "entityTypeUri": "configuration/entityTypes/HCP",
      "matchRuleUri": "configuration/entityTypes/HCP/matchGroups/MatchByMiddleName",
      "matchRuleName": "Match by MiddleName",
      "matchRuleType": "suspect",
      "matchRuleAction": "POTENTIAL_MATCH",
      "entityMatchScore": 0,
      "attributes": {
        "FirstName": [
          {
            "value": "GGG1"
          }
        ],
        "Identifiers": [
          {
            "value": {
              "Type": [
                {
                  "value": "TYPE2"
                }
              ]
            }
          }
        ]
      },
      "crosswalks": [
        {
          "value": "cv51hpa",
          "type": "Reltio"
        }
      ]
    },
    {
      "uri": "entities/0000ZA9",
      "entityTypeUri": "configuration/entityTypes/HCP",
      "matchRuleUri": "configuration/entityTypes/HCP/matchGroups/MatchByMiddleName",
      "matchRuleName": "Match by MiddleName",
      "matchRuleType": "suspect",
      "matchRuleAction": "POTENTIAL_MATCH",
      "entityMatchScore": 0,
      "attributes": {
        "FirstName": [
          {
            "value": "GGG2"
          }
        ],
        "Identifiers": [
          {
            "value": {
              "Type": [
                {
                  "value": "TYPE2"
                }
              ]
            }
          }
        ]
      },
      "crosswalks": [
        {
          "value": "zaj3hpj",
          "type": "Reltio"
        }
      ]
    },
    {
      "uri": "entities/0000lwv",
      "entityTypeUri": "configuration/entityTypes/HCP",
      "matchRuleUri": "configuration/entityTypes/HCP/matchGroups/MatchByMiddleName",
      "matchRuleName": "Match by MiddleName",
      "matchRuleType": "suspect",
      "matchRuleAction": "POTENTIAL_MATCH",
      "entityMatchScore": 0,
      "attributes": {
        "FirstName": [
          {
            "value": "GGG3"
          }
        ],
        "Identifiers": [
          {
            "value": {
              "Type": [
                {
                  "value": "TYPE2"
                }
              ]
            }
          }
        ]
      },
      "crosswalks": [
        {
          "value": "qcre1mn",
          "type": "Reltio"
        }
      ]
    }
  ]
}

Example - external match output

A new matchRuleActionLabel field is added to the external match output. If no label is configured for the actionThreshold parameter, then the matchRuleActionLabel field doesn't appear in the output JSON file. The relevance value is represented by the matchRelevance field.

{
  "inputRecordId": "entityUri",
  "matchedEntities": [
    {
      "uri": "matchedEntityUri",
      "entityTypeUri": "configuration/entityTypes/HCP",
      "matchRuleUri": "configuration/entityTypes/HCP/matchGroups/PotentialMatchByEmail",
      "matchRuleName": "HCP by Fuzzy Email",
      "matchRuleType": "relevance_based",
      "matchRuleAction": "POTENTIAL_MATCH",
      "entityMatchScore": 0,
      "matchRelevance": 0.85,
      "matchRuleActionLabel": "suspect match for review",
      "crosswalks": [
        ...
      ]
    }
  ]
}

Accelerate the Value of Data

External match API

Request

Request Parameters

Input file format

Output file format

External match job statistics

CSV external match report

Single-line JSON external match report

Multi-line JSON external match report

Example - external match output

Footer