Search for potential matches for entity specified in JSON with scoring

Learn more about how the Scored Matches API returns potential matches with scoring for entities provided in the JSON request body, based on rules in the entity type configuration.

The Scored Matches API returns potential matches with scoring for entities provided in the JSON request body, based on rules in the entity type configuration.

For each matched entity, the score is calculated as follows:

totalScore = MAX(standaloneScore of all matched rules) + SUM(incrementalScore of ALL matched rules including the rule from standaloneScore)

Request

POST {TenantURL}/entities/_scoredmatches

Table 1. Parameters
Parameter		Required	Description
Headers	`Authorization`	Yes	Information about authentication access token in `Bearer <accessToken>` format. For more information, see Authentication API.
Headers	Body	Yes	JSON array with objects representing entity objects to be matched.
Query	`max`	No	Defines the maximum number of returned matches. The default value is 200.
	`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`
	`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.
	`select`		Comma-separated list of properties from the entity structure that must be returned in a response. Allows you to return a partial entity object. Example: `select=uri,label,attributes,crosswalks from the referenced object` To ensure improved performance of `_scoredMatches`, properly define the properties list in the select parameter. The possible variants are: `uri and/or type (select=uri,type)`. No objects are loaded. The most efficient and recommended way. Simple or nested attributes from the object are specified. A lightweight operation is performed to retrieve the object without references. `no select; select=attributes`, contains some reference attributes that are loaded with the object. The above mentioned optimizations work only if there is no configured data security for the entity type, else the object is loaded fully. If there are a a large number of matches for input entities, then the response size can be very large. The size is limited to 100 MB. In such a case, it is recommended to reduce the number of input entities and decrease the value of the 'max' parameter. If the Request has the select parameter, there must not be any space between the query parameters.
	`offset`	No	Integer value that can be used to organize pagination in the response. The default value is 0.
	`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 totrue, 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.

Response

Returns all matches of posted entity with scoring and rules the entity matched on. Note that an error can be returned instead of entities collection.

For relevance-based rules, including FERN and composite rules, matchGroups[] can also include optional relevance and actionLabel values. These fields are not returned for regular score-based rules.

Request

 POST {TenantURL}/entities/_scoredmatches
 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"
 				}],
 				"Zip": [{
 					"value": {
 						"Zip5": [{
 							"value": "123456"
 						}]
 					}
 				}]
 			}
 		}],
 		"ME": [{
 			"value": "123"
 		}]
 	}
 }]

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:

[{
	"index": 0,
	"object": [{
		"URI": "entities/HCP.testSearchDuplicatesForNonExistentEntity.2",
		"type": "configuration/entityTypes/HCP",
		"matchScore": 51,
		 "matchGroups": [
          {
            "uri": "configuration/entityTypes/HCP/matchGroups/FERNIndividualModelMethodV2",
            "label": "Pretrained FERN for HCP",
            "type": "composite",
            "scope": "ALL",
            "useOvOnly": "false",
            "relevance": 0.90,
		"actionLabel": "High confidence",
            "scoreStandalone": 0,
            "scoreIncremental": 0
          },
          {
            "uri": "configuration/entityTypes/HCP/matchGroups/BaseRule5",
            "label": "BaseRule5: Fuzzy (First Name, Last Name); Exact(Email)",
            "type": "suspect",
            "scope": "ALL",
            "useOvOnly": "false",
            "scoreStandalone": 85,
            "scoreIncremental": 20
          }
        ],
		"attributes": {...
		},
		...
	}, {
		"URI": "entities/HCP.testSearchDuplicatesForNonExistentEntity.1",
		"type": "configuration/entityTypes/HCP",
		"matchScore": 81,
		"matchGroups": [
			"configuration/entityTypes/HCP/matchGroups/PersonByNameSuffixAddrAuto",
			"configuration/entityTypes/HCP/matchGroups/PersonByNameSuffixDegreeAddrSuspect",
			"configuration/entityTypes/HCP/matchGroups/PersonByNameSuffixDegreeAddrAuto"
		],
		"attributes": {...
		},
		...
	}],
	"successful": true
}]

Unify and manage your data

Search for potential matches for entity specified in JSON with scoring

Footer