Verifying Matches

Learn how to search for potential matches in JSON array entities in your tenant.

Use the Verify Matches to search for potential matches in JSON array entities in your tenant.

To optimize matching performance, the API performs matching in this order:

Match tokens
Match attributes

The Hub Profile perspective displays entities as potential matches based on the value of the following parameters in this API response:

intersection: This field must not be empty.
matched: This field is true if matched by both documents and tokens; otherwise, it is false.
matchedByDocuments: This field is true if matched by documents; otherwise, it is false.

Tip: We recommend that you first run this Verify Matches without the rules parameter to see if any token intersections are present. When you run this API with the rules parameter, the response contains only tokens for the specified rule or rules. The matching process compares tokens generated for all of the match rules, not just the rules specified in the API.

Request

POST {TenantURL}/entities/_verifyMatches

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

Table 1. Parameters
	Name	Required	Description	Examples
Headers	CustomerTenant	Yes	Customer Tenant ID.	-
Headers	DataTenant	Yes	Data Tenant ID.	-
URI Parameters	rules	Yes	Enabled match rules.	`POST {TenantURL}/entities/_verifyMatches?rules=configuration/entityTypes/HCP/matchGroups/PersonByNPISuspect2`
	show	Optional	Determines the information that will be available in a response. The user can assign the following values: brief: Returns only rules and their explanations (current behavior) full: Returns information about match documents values and entities versions	If show is set to full, the output has the following format: `{ "matchDocuments": { "first": { "areEqual": true/false, "databaseDocument": {...}, "generatedDocument": {...} }, "second": { "areEqual": true/false, "databaseDocument": {...}, "generatedDocument": {...} } }, "versions": { "first": { "EntityVersion": value, "MatchDocumentVersion": value }, "second": { "EntityVersion": value, "MatchDocumentVersion": value } }, "rules": { "Rule1": {explanation}, "Rule2": {explanation}, ... } }`
	documentsFromDatabase	Optional	The default value is false. If set to true, for existing entities, their actual documents from database will be used for explanation. If set to false, the documents will be regenerated for explanation (expected behavior).
	checkOvercollisionedTokens	Optional	The default value is `true`. When it is `true`, the API checks if the match token phrases are marked as overcollisioned in the database. If yes, the match token phrases are represented as overcollisioned and removed from the intersection list. If set to `false`, the tokens list might contain overcollisioned tokens.
	time	Optional	If this parameter is specified, it returns the match document and the match token phrases built for the entity according to the entity state and business configuration state at the specified time. If you specify the `time` parameter, then the `db` parameter is ignored and effectively set to `false`. When the `time` parameter is specified, the API results may show some discrepancy based on the following: The match documents and match tokens are generated on-the-fly because the historical information about match documents and match tokens is not available. The explanation is built by using the current state of the API. As a result, if the match or survivorship rules have changed after the specified time, then the results of the explanation might differ from the actual results for the specified time. If an entity refers to data that may change over time, such as lookups or environment configuration, user preferences, or permissions, then the currently available data or configuration is taken. The auto-generated values might not correspond to the actual ones. The L3 configuration is selected by the timestamp of the history entry. If an entity or the tenant configuration does not exist, then the request fails with a 404 error.
Body		Yes	A pair of entities to be matched.	`{ "first":"entities/0000I77", "second":"entities/0000BLK" } { "first": { "type": "configuration/entityTypes/Individual", "attributes": { "FirstName": [ { "value": "Ernest" } ], "MiddleName": [ { "value": "Miller" } ], "LastName": [ { "value": "H." } ] } }, "second": { "type": "configuration/entityTypes/Individual", "attributes": { "FirstName": [ { "value": "Ernest" } ], "MiddleName": [ { "value": "M." } ], "LastName": [ { "value": "Hemingway" } ] } } }`

Request

Returns the match explanation for each matching group.

Example

POST /Abc/entities/_verifyMatches
{
   "first":{
      "type":"configuration/entityTypes/HCP",
      "attributes":{
         "LastName":[
            {
               "value":"Stark"
            }
         ],
         "FirstName":[
            {
               "value":"Ronald"
            }
         ],
         "Address":[
            {
               "value":{
                  "City":[
                     {
                        "value":"winterfell"
                     }
                  ],
                  "StateProvince":[
                     {
                        "value":"north"
                     }
                  ],
                  "Country":[
                     {
                        "value":"westeros"
                     }
                  ]
               }
            }
         ]
      },
      "crosswalks":[
         {
            "type":"configuration/sources/TWITTER",
            "value":"test1"
         }
      ]
   },
   "second":{
      "uri":"entities/03w0bJo"
   },
   "matchGroups":[
      {
         "uri":"configuration/entityTypes/HCP/matchGroups/RelevanceBasedRule",
         "label":"Automatic on load Addresses",
         "type":"relevance_based",
         "useOvOnly":"false",
         "rule":{
            "exact":[
               "configuration/entityTypes/HCP/attributes/FirstName",
               "configuration/entityTypes/HCP/attributes/LastName"
            ],
            "weights":[
               {
                  "attribute":"configuration/entityTypes/HCP/attributes/FirstName",
                  "weight":"1"
               },
               {
                  "attribute":"configuration/entityTypes/HCP/attributes/LastName",
                  "weight":"1"
               }
            ],
            "actionThresholds":[
               {
                  "type":"potential_match",
                  "threshold":"0.6-1.0"
               }
            ]
         }
      },
      {
         "uri":"configuration/entityTypes/HCP/matchGroups/RelevanceExactFirstName",
         "label":"Will be bypassed",
         "type":"relevance_based",
         "useOvOnly":"false",
         "rule":{
            "exact":[
               "configuration/entityTypes/HCP/attributes/FirstName"
            ],
            "weights":[
               {
                  "attribute":"configuration/entityTypes/HCP/attributes/FirstName",
                  "weight":"1"
               }
            ],
            "actionThresholds":[
               {
                  "type":"potential_match",
                  "threshold":"0.6-1.0"
               }
            ]
         }
      },
      {
         "uri":"configuration/entityTypes/HCP/matchGroups/SuspectExactMiddleName",
         "label":"Exact middle name",
         "type":"suspect",
         "useOvOnly":"false",
         "rule":{
            "exact":[
               "configuration/entityTypes/HCP/attributes/MiddleName"
            ]
         }
      }
   ]
}

Response

Note: In relevance-based rules, the match property is excluded from the Verify Matches response, at the attribute level.


{
  "summary": [
    "There are common match tokens. These entities are considered as match candidates and will be checked according to the list of common applicable match rules.",
    "There are bypassed rules for the given entity type. Bypassed match rules do not participate in the matching process.",
    "No manually set 'not-matches' are found for the entities"
  ],
  "matchTokensSummary": {
    "firstTotal": 1,
    "secondTotal": 1,
    "common": [
      "ronald:stark"
    ]
  },
  "applicableMatchGroups": {
    "first": [
      "configuration/entityTypes/HCP/matchGroups/RelevanceBasedRule",
      "configuration/entityTypes/HCP/matchGroups/RelevanceExactFirstName"
    ],
    "second": [
      "configuration/entityTypes/HCP/matchGroups/RelevanceBasedRule",
      "configuration/entityTypes/HCP/matchGroups/RelevanceExactFirstName"
    ],
    "both": [
      "configuration/entityTypes/HCP/matchGroups/RelevanceBasedRule",
      "configuration/entityTypes/HCP/matchGroups/RelevanceExactFirstName"
    ],
    "bypassed": [
      "configuration/entityTypes/HCP/matchGroups/RelevanceExactFirstName"
    ]
  },
  "rules": {
    "configuration/entityTypes/HCP/matchGroups/RelevanceBasedRule": {
      "label": "Automatic on load Addresses",
      "matched": true,
      "matchAction": "POTENTIAL_MATCH",
      "matchedByDocuments": true,
      "bypassed": false,
      "relevance": 1.0,
      "useOvOnly": false,
      "matchTokens": {
        "first": {
          "foundInMatchTables": false,
          "tokens": [
            "ronald:stark"
          ],
          "tokensGenerated": 1
        },
        "second": {
          "foundInMatchTables": false,
          "tokens": [
            "ronald:stark"
          ],
          "tokensGenerated": 1
        },
        "intersection": {
          "tokens": [
            "ronald:stark"
          ]
        }
      },
      "rule": {
        "relevance": 1.0,
        "and": [
          {
            "exact": {
              "FirstName": {
                "ignoreInToken": false,
                "relevance": 1.0
              },
              "LastName": {
                "ignoreInToken": false,
                "relevance": 1.0
              }
            },
            "relevance": 1.0
          }
        ]
      }
    },
    "configuration/entityTypes/HCP/matchGroups/RelevanceExactFirstName": {
      "label": "Will be bypassed",
      "matched": false,
      "matchAction": "POTENTIAL_MATCH",
      "matchedByDocuments": true,
      "bypassed": true,
      "relevance": 1.0,
      "useOvOnly": false,
      "matchTokens": {
        "first": {
          "foundInMatchTables": false,
          "tokens": [
            "ronald"
          ],
          "tokensGenerated": 1
        },
        "second": {
          "foundInMatchTables": false,
          "tokens": [
            "ronald"
          ],
          "tokensGenerated": 1
        },
        "intersection": {
          "tokens": [
            "ronald"
          ]
        }
      },
      "rule": {
        "relevance": 1.0,
        "and": [
          {
            "exact": {
              "FirstName": {
                "ignoreInToken": false,
                "relevance": 1.0
              }
            },
            "relevance": 1.0
          }
        ]
      }
    },
    "configuration/entityTypes/HCP/matchGroups/SuspectExactMiddleName": {
      "label": "Exact middle name",
      "matched": false,
      "matchedByDocuments": false,
      "bypassed": false,
      "useOvOnly": false,
      "matchTokens": {
        "first": {
          "foundInMatchTables": true,
          "tokensGenerated": 0
        },
        "second": {
          "foundInMatchTables": true,
          "tokensGenerated": 0
        },
        "intersection": {}
      },
      "rule": {
        "and": [
          {
            "exact": {
              "MiddleName": {
                "match": false,
                "ignoreInToken": false
              }
            }
          }
        ]
      },
      "manualMatches": {
        "notMatches": {
          "03w0bJo": [
            {
              "id": "02Yae1",
              "updatedTime": 1699463284016,
              "updatedBy": "User"
            }
          ]
        },
        "asMatches": {
          "03w0bJo": [
            {
              "id": "01oRn9",
              "updatedTime": 1699463274839,
              "updatedBy": "User"
            }
          ]
        },
        "effectiveNotMatches": {
          "03w0bJo": [
            "02Yae1"
          ]
        },
        "effectiveAsMatches": {
          "03w0bJo": [
            "01oRn9"
          ]
        }
      }
    }
  }
}

This table describes the fields in the response.


Field	Description
`foundInMatchTables`	Indicates whether `C* MATCH_TOKENS CF` contains all the listed tokens.
`tokens`	Provides a list of all the match tokens generated for the match rules configured for the entity type.
`intersection`	Provides a list of common tokens for the entities.
`setAsNotMatch`	Indicates that the entities are marked as "Not a Match".
`alreadySubscribed`	Shows that the CT entity is already subscribed to the DT entity
`label`	Displays the description of the match rule
`useOvOnly`	Displays the OV strategy chosen for the match rule.
`ignoreInToken`	Excludes the particular attribute from the match token.
`summary`	Contains information, for the checked entities, on: The existence, or nonexistence of common tokens, and whether they are considered as match candidates. Applicable bypassed rules. Manually set matches and not-matches.
`matchTokensSummary`	Contains the following details: Information about the total number of tokens generated for both entities from the body request according to the bypassed rules (tokens generated by the bypassed rules are not counted). Match tokens common to both entities (excluding tokens generated by bypassed rules, and, overcollisioned tokens if detected).
`applicableMatchGroups`	Displays the list of match rules applicable to the `first`, `second`, or `both` entities in the request body. Also, displays the `bypassed` rules if they exist. Note: If a rule is bypassed, the `matched` field will always be `false.`
`manualMatches`	Displays information when any of the entities in the request body are manually set `asMatches`, or as `notMatches`.

Unify and manage your data

Verifying Matches

Request

Response

Footer