External match API
Learn about the external match API operation 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 operation to match records stored externally in a file with entities in a Reltio tenant. To use this API operation, you must provide an input file that contains the records to be matched. This API operation counts 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, GCP, 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. Use storage parameters for only one cloud provider per request. 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
Tenant admin role is required: POST {ApplicationURL}/api/{tenantId}/externalMatch
The API runs the external match job which calculates the match pairs for the input entities. The job runs for match rules with scope ALL and EXTERNAL only. For the API specification, see the external match operation on the Developer Portal.
Request Parameters
These are the path and query request parameters:
| Parameters | Required | Description |
|---|---|---|
tenantId | Yes | Identifier 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:
json. Constants aren't case sensitive.Note: Exporting attributes is supported for json_v2 format only. |
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. |
bucket | No | Defines the bucket where the source file must reside and where the result file will be created. |
path | No | Determines the path to a source file in a bucket (including folders, if necessary). |
pathOut | No | 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. |
entitiesLimit | No | Defines the number of entities to be processed from the source. |
skipEntitiesCount | No | Defines the number of entities to skip 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: |
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. |
Body
You may pass the query parameters in the body rather than in the query string, if you prefer.
If
fileFormat=json_v2, then you may also use these body parameters: | Parameters | Required | Description |
|---|---|---|
selectAttributes | No | Array of string values that allow you to select attributes to be included in the output file. Examples
|
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:
|
Input file format
The input file can 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"}]}
Note: Each entity must occupy only one row of the input file.
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. |
| Field | Description |
|---|---|
uri | URI of the matched entity. |
entityTypeUri |
Entity Type of the matched entity. |
matchRuleUri |
Match rule URI of the matched entity. |
|
| 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. |
|
| 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
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,,
Multi-line JSON external match report
Request:
http://localhost:8080/reltio/api/Merill/externalMatch?
path=inputData.json&bucket=rp31694externalmatch&s3Region=us-east-
1&awsAccessKey=ACCESSKEY&awsSecretKey=SECRETKEY&pathOut=jobResult.json&entityType=HCP&tenantId=Merill
&fileFormat=json&entitiesLimit=3&skipEntitiesCount=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"
]
}
Single line JSON external match report
Request:
http://localhost:8080/reltio/api/Merill/externalMatch?
path=inputData.json&bucket=rp31694externalmatch&s3Region=us-east-
1&awsAccessKey=ACCESSKEY&awsSecretKey=SECRETKEY&pathOut=jobResult.json&entityType=HCP&tenantId=Merill
&fileFormat=json_v2&entitiesLimit=3&skipEntitiesCount=2&distributed=false
Body:
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 {
"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": [
...
]
}
]
}
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.