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.
	`activeness`	No	When it’s set to `active`, only active entities are listed in the response for potential matches. Otherwise, all entities are listed as potential matches.
	`deep`	No	Limits the depth of transitive matches. Default is 5.
	`showObject`	No	URI of an entity to show a page on which this entity must be present.
	`offset`	No	Integer value that can be used to organize pagination in the response. The default value is 0.
	`type`	No	Filter 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.

Example of default request

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

Example of default 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",
                ...
            },
			"createdTime": 1709908613750
        },
        {
            "negativeRules" : [
                "configuration/entityTypes/Individual/matchGroups/Negative1"
            ],
            "object" : {
                "uri": "entities/22",
                "type": "configuration/entityTypes/Individual",
                ...
            },
			"createdTime": 1709908613750
        }
     },
    "configuration/entityTypes/Individual/matchGroups/SuspectMatch": [
        {
            "object" : {
                "uri": "entities/97",
                "type": "configuration/entityTypes/Individual",
                ...
            },
			"createdTime": 1709908613750
        }
    ]
}

Example with the transitive parameter

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


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

Example with the showActions parameter

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",
  ...
     }
   ]
 }
}

Example response for a 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.

Unify and manage your data

Potential matches API

Request

Response

Example of default request

Example of default response

Example with the transitive parameter

Example with the showActions parameter

Example response for a relevance-based match rule

Footer