Search For Potential Matches for Entity Specified in JSON

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.
	`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
204938 ca-2 cf7-44 b0-b11a-1 b4c59984512[{
			"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
204938 ca-2 cf7-44 b0-b11a-1 b4c59984512[{
	"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