Accelerate the Value of Data

Potential matches API

Learn to get details about all potential matches based on rules in entity type configuration.

Request

GET {TenantURL}/entities/{entity object URI}/_matches
Table 1. Parameters
Parameter Required Description
Headers Authorization Yes Information about authentication access token in the format "Bearer <accessToken>" (see details in Authentication API).
Query transitive No Flag to return transitive matches as separate group, default value is false.
forceMatch No Matches are calculated instantly, default value if false .
max No Defines maximum number of returned matches (for each entity).
options No Comma-separated list of different options, which affect the entity's JSON content in a response. Available options:
  • ov=false- disabled by default. The entity's JSON will have hidden attributes if this option is enabled.
  • ovOnly- returns attributes having the ov=true flag.
  • nonOvOnly- returns attribute values that have the ov=false flag. If you have a nested or reference attribute value, where ov=true but subattributes have the ov=false flag, these subattributes won’t appear in the response.
activenessNoWhen it’s set to active, only active entities are listed in the response for potential matches. Otherwise, all entities are listed as potential matches.
deepNoLimits the depth of transitive matches. Default is 5.
showObjectNoURI of an entity to show a page on which this entity must be present.
offsetNoInteger value that can be used to organize pagination in the response. The default value is 0.
typeNoFilter potential matches based on the type of match group. Available values:
  • automatic- filters records that were matched automatically.
  • relevance_based- filters records that were matched based on relevance.
  • suspect- filters records that are suspected to be a match.

Response

Returns all matches grouped by match groups.

Request

GET {TenantURL}/entities/10/_matches
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512

Response

{
    "configuration/entityTypes/Individual/matchGroups/AutoMatch": {
        {
            "negativeRules" : [
                "configuration/entityTypes/Individual/matchGroups/Negative1",
                "configuration/entityTypes/Individual/matchGroups/Negative2"
            ],
            "object" : {
                "uri": "entities/15",
                "type": "configuration/entityTypes/Individual",
                ...
            }
        },
        {
            "negativeRules" : [
                "configuration/entityTypes/Individual/matchGroups/Negative1"
            ],
            "object" : {
                "uri": "entities/22",
                "type": "configuration/entityTypes/Individual",
                ...
            },
        }
     },
    "configuration/entityTypes/Individual/matchGroups/SuspectMatch": [
        {
            "object" : {
                "uri": "entities/97",
                "type": "configuration/entityTypes/Individual",
                ...
            }
        }
    ]
}

Response when the transitive parameter is used

Returns all matches grouped by match groups. Transitive matches are shown in a separate group.

Request

GET {TenantURL}/entities/10/_matches?transitive=true
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512

Response

GET {TenantURL}/entities/10/_matches?transitive=true 
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512 
{
    "configuration/entityTypes/Individual/matchGroups/AutoMatch": {
        {
            "negativeRules" : [
                    "configuration/entityTypes/Individual/matchGroups/Negative1",
                    "configuration/entityTypes/Individual/matchGroups/Negative2"
            ],
            "object" : {
                "uri": "entities/15",
                "type": "configuration/entityTypes/Individual",
                ...
            }
        }
    },
    "transitive": [
        {
            "object" : {
                "uri": "entities/22",
                "type": "configuration/entityTypes/Individual",
                ...
            },
            "object" : {
                "uri": "entities/97",
                "type": "configuration/entityTypes/Individual",
                ...
            }
        }
    ]
}

Response when the show actions parameter is used

Request

 GET {TenantURL}/entities/10/_matches?showActions=true
 Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
            

Response

{
 "configuration/entityTypes/Individual/matchGroups/AutoMatch": {
   "AUTO_MERGE": [
     {
       "uri": "entities/33",
       "type": "configuration/entityTypes/Individual",
		...
     }
   ]
 },
 "configuration/entityTypes/Individual/matchGroups/SuspectMatch": {
   "POTENTIAL_MATCH": [
     {
       "uri": "entities/44",
       "type": "configuration/entityTypes/Individual",
  ...
     }
   ]
 }
}

Response for relevance-based match Rule

Response

{
  "configuration/entityTypes/HCP/matchGroups/PotentialMatchByEmail": [
    {
      "object": {
        "uri": "entities/Man2",
        "type": "configuration/entityTypes/HCP",
        "createdBy": "jenya",
        "createdTime": 1611235198144,
        "updatedBy": "jenya",
        "updatedTime": 1611235198144,
        "attributes": {
          "Email": [
            ...
          ]
        },
        "crosswalks": [
          ...
        ],
        "analyticsAttributes": {},
        "label": "",
        "secondaryLabel": ""
      },
      "relevance": 1,
      "matchActionLabel": "candidate for merge"
    }
  ]
}

New fields relevance and matchActionLabel are added to the output. These fields appear only for the relevance-based match groups. The relevance field shows the value of the relevance between the two entities according to the particular match rule. The matchActionLabel field is derived from the actionThreshold parameter of the match rule and provides some hints for the data steward. If no label is configured for the actionThreshold parameter, then the matchActionLabel field doesn’t appear in the response.