Search For Potential Matches for Entity Specified in JSON

Learn more about getting potential matches, based on the rules in the entity type configuration, for entities that you provide as JSON in the request body.

Returns potential matches based on rules in entity type configuration for entities provided inside request body as JSON.

Request

POST {TenantURL}/_matches

Table 1. Parameters
Parameter		Required	Details
Headers	`Authorization`	Yes	Information about authentication access token in `Bearer <accessToken>` format. For more information, see Authentication API.
	`Body`	Yes	JSON array with objects representing entity objects to be matched.
Query	`activeness`	No	When it is set to `active`, only active entities are listed in the response for the potential matches. Otherwise, all entities are listed as potential matches.
	`cleanse`	No	When it is set to true, the API cleanses the attribute values of the entities. Then the cleansed entities are matched with the entities in the tenant. The default value is false.
	`calculateOvForReferences`	No	When it is set to `true`, the crosswalks of each entity in the request body are also applied to the entities and relationships behind its reference attributes, so that operational values of reference sub-attributes are calculated with the tenant's survivorship rules. If omitted, the tenant-level setting applies. It is `false` unless Support has enabled it for your tenant.
	`max`	No	Defines the maximum number of returned matches.
	`options`	No	Comma-separated list of different options, which affect entity's JSON content in the response. Available options: `ov=false`- disabled by default, entity's JSON will contain hidden attributes if this option is enabled. `ovOnly`- return only attribute values that have `ov=true` flag. `nonOvOnly`- return only attribute values that have `ov=false` flag. If you have a nested or reference attribute value where `ov=true`, but sub-attributes where `ov=false`, then these sub-attributes will not appear in the response.
	`rules`	No	Defines match rule `URI`s to be used in matching. This parameter can be used several times in a request. Each time the parameter must specify one match rule URI, for example: `rules=configuration/entityTypes/Individual/matchGroups/matchGroup1&rules= configuration/entityTypes/Individual/matchGroups/matchGroup2`

Response

Returns all matches of posted entity grouped by match groups based on the scope. The response only includes matches for the cases where the scope = "external" or "all" and does not include scope = "internal".

Note: Under any match group an error could be returned instead of entities collection.

Request

POST {
	TenantURL
}
/entities/_matchesHeaders: Authorization:
	Bearer
{your-access-token}[{
			"type": "configuration/entityTypes/HCP",
			"attributes": {
				"FirstName": [{
					"value": "William"
				}],
				"MiddleName": [{
					"value": "James"
				}],
				"LastName": [{
					"value": "Harley"
				}],
				"SuffixName": [{
					"value": "Mr."
				}],
				"Degrees": [{
					"value": {
						"Degree": [{
							"value": "Lord"
						}]
					}
				}],
				"Address": [{
						"value": {
							"AddressLine1": [{
									"value": "USA, VI, Milwakee, Liberty
									plate 1234 " }
								], "ZipPostalCode": [{
									"value": "123456"
								}]
							}
						}]
				}
			}]

Note: If the request contains an individual cleanser for any of the attributes, such as phone, email, address, and so on, it is not cleansed before matching because the API uses only cleansers that are specified in the match rules configuration.

Response

In the response, for every entity:

POST {
	TenantURL
}
/entities/_matches
Headers: Authorization: Bearer
{your-access-token}[{
	"index": 0,
	"object": {
		"configuration/entityTypes/HCP/matchGroups/PersonByNameSuffixDegreeAddrAuto": [{
			"URI": "entities/HCP.1",
			"type": "configuration/entityTypes/HCP",
			"createdBy": "aleshka",
			"createdTime": 1369153550476,
			"updatedTime": 1369153550476,
			"attributes": {
				"FirstName": [{
					"type": "configuration/entityTypes/HCP/attributes/FirstName",
					"ov": true,
					"value": "william",
					"URI": "entities/HCP.1/attributes/FirstName/0"
				}],
				"LastName": [{
					"type": "configuration/entityTypes/HCP/attributes/LastName",
					"ov": true,
					"value": "Harley",
					"URI": "entities/HCP.1/attributes/LastName/2"
				}],
				"MiddleName": [{
					"type": "configuration/entityTypes/HCP/attributes/MiddleName",
					"ov": true,
					"value": "James",
					"URI": "entities/HCP.1/attributes/MiddleName/1"
				}],
				"SuffixName": [{
					"type": "configuration/entityTypes/HCP/attributes/SuffixName",
					"ov": true,
					"value": "Mr.",
					"URI": "entities/HCP.1/attributes/SuffixName/3"
				}],
				"Degrees": [{
					"label": "Lord",
					"value": {
						"Degree": [{
							"type": "configuration/entityTypes/HCP/attributes/Degrees/attributes/Degree",
							"ov": true,
							"value": "Lord",
							"URI": "entities/HCP.1/attributes/Degrees/4/Degree/5"
						}]
					},
					"ov": true,
					"URI": "entities/HCP.1/attributes/Degrees/4"
				}]
			},
			"crosswalks": [{
				"URI": "entities/HCP.1/crosswalks/0",
				"type": "configuration/sources/AMS",
				"value": "AMS-HCP.1",
				"attributes": ["entities/HCP.1/attributes/Degrees/4",
					"entities/HCP.1/attributes/Degrees/4/Degree/5",
					"entities/HCP.1/attributes/MiddleName/1", "entities/HCP.1/attributes/FirstName/0",
					"entities/HCP.1/attributes/LastName/2", "entities/HCP.1/attributes/SuffixName/3"
				]
			}, {
				"URI": "entities/HCP.1/crosswalks/2",
				"type": "configuration/sources/Reltio",
				"value": "HCP.1",
				"attributes": ["entities/HCP.1/attributes/Degrees/4",
					"entities/HCP.1/attributes/Degrees/4/Degree/5",
					"entities/HCP.1/attributes/MiddleName/1", "entities/HCP.1/attributes/FirstName/0",
					"entities/HCP.1/attributes/LastName/2", "entities/HCP.1/attributes/SuffixName/3"
				]
			}],
			"label": " "
		}]
	},
	"successful": true
}]

Unify and manage your data

Search For Potential Matches for Entity Specified in JSON

Footer