Verifying matches

Learn how to simulate and explain matching behavior between two entities using configured or custom match rules.

Use the verify matches API operation to simulate how two entities would match based on your match rules. You can provide either URIs of existing tenant entities or raw JSON definitions in the request. The operation supports default match rules from your configuration, specific match rule URIs via query parameters, or custom ad hoc rules defined directly in the request body. This makes it useful for rule tuning, diagnostics, and understanding match outcomes.

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

Match tokens
Match attributes

When both attribute values come from the same crosswalk, they may be treated as operational values (OV) during in-memory match document generation. This can result in different match behavior than in persisted tenant data. To better reflect actual tenant logic, use entity URIs and set documentsFromDatabase to true in your request.

The Hub Profile perspective displays entities as potential matches based on the value of the following parameters from this API operation's 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 operation without the rules parameter to see if any token intersections are present. When you run this operation 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 operation.

Request

POST {TenantURL}/entities/_verifyMatches

The specification of this operation is available on the Developer Portal.

Note: If the request contains an individual cleanser for any of the attributes, such as phone, email, or address, it isn't used before matching because this operation only uses 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	Optional	A comma-separated list of match group URIs. If omitted, the default match groups are used. You can also define custom rules directly in the request body using the `matchGroups` parameter.	`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 operation 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 operation 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 operation. 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

Get 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 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