Verifying matches

Learn more about how to use the Verify Matches API to explain matching behavior for either two entities or two raw serialized match documents.

Use the verify matches to simulate how your match rules evaluate two inputs. You can compare two entities by using first and secondrequest parameters, or two raw serialized match documents by using firstDocument and secondDocument request parameters. The operation supports the default match rules in your configuration, specific match-group URIs through the rules query parameter, or custom match groups defined in the request body. Use this operation to adjust match rules rules, diagnose issues, and understand match outcomes.

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

Match tokens
Match attributes

In entity mode, when both attribute values come from the same crosswalk, the operation treats them as operational values (OV) during in-memory match-document generation. In some cases, this treatment produces results that differ from persisted tenant data. To reflect persisted tenant logic more closely, use entity URIs and set documentsFromDatabase=true.

In entity mode, entities appear as potential matches in Hub Profile based on the following response values:

intersection: This field must not be empty.
matched: This field is true if the entities are match candidates and the rule determines a match; otherwise, it is false.
matchedByDocuments: This field is true if the match documents satisfy the configured rule logic; otherwise, it is false.

Tip: We recommend that you first run this operation without the rules parameter to review all candidates discovered and their evaluation results. When you run this operation with the rules parameter, the response contains results for the specified rule or rules. The matching process evaluates candidate discovery across all applicable match rules, not just the rules specified in the operation.

Supported request modes

_verifyMatches accepts exactly one complete input mode per request.

For the entity mode, provide entities in the first and second request parameters. Each value must be either a URI string that points to an existing entity or inline entity JSON. For the raw match-document mode, provide inputs in the firstDocument and secondDocument request parameters. Each value must be a serialized match document, and both documents must resolve to the same entity type.

Note: Do not mix the entity mode and raw-document modes in a single request. Supply both sides of a pair. For example, providing only firstDocument and omitting secondDocument, results in a validation error.

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.	—
Query 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. Rule filtering works the same way in entity mode and raw match-document mode.	`POST {TenantURL}/entities/_verifyMatches?rules=configuration/entityTypes/HCP/matchGroups/PersonByNPISuspect2`
	show	Optional	Determines the information available in the response. Use one of the following values: `brief`: Returns rule explanations only. `full`: Returns additional explanation details. In entity mode, this includes match-document values and entity versions. In raw match-document mode, entity-only sections are returned as `null`.	If entity mode, 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. In entity mode, if set to `true`, the operation uses persisted match documents for existing entities instead of regenerating them in memory. This parameter does not apply to raw match-document mode.	—
	checkOvercollisionedTokens	Optional	The default value is `true`. When set to `true`, the operation checks whether match-token phrases are marked as overcollisioned in the database. Overcollisioned phrases are removed from the intersection list. If set to `false`, the token list can include 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 in real time 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.	—

Request body

The following table describes the request body parameters.


Name	Required	Description
`first`	Yes, in entity mode	First input to compare. Provide an entity URI or inline entity JSON.
`second`	Yes, in entity mode	Second input to compare. Provide an entity URI or inline entity JSON.
`firstDocument`	Yes, in raw match-document mode	First serialized match document to compare. This is a match-document payload, not a regular entity create or update payload.
`secondDocument`	Yes, in raw match-document mode	Second serialized match document to compare. This is a match-document payload, not a regular entity create or update payload.
`matchGroups`	No	Custom match groups to evaluate as part of the request. Custom match groups work the same way in entity mode and raw match-document mode.

Example request

Example request: entity mode using inline entity JSON and custom match groups

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"
            ]
         }
      }
   ]
}

Example request: raw match-document mode

POST {TenantURL}/entities/_verifyMatches
{
    "firstDocument": 
{
        "~@i": "doc-001",
        "$$_entity_type_$$": [
            "Individual"
        ],
        "$$_entity_type_$$~.@ps": [
            "10"
        ],
        "FirstName": [
            "william"
        ],
        "FirstName~.@ps": [
            "10"
        ],
        "LastName": [
            "harley"
        ],
        "LastName~.@ps": [
            "10"
        ],
        "_mRuleUri": [
            "e§Individual§SameFirstName",
            "e§Individual§SameLastName",
            "e§Individual§SameFirstLastName"
        ],
        "_mRuleUri~.@ps": [
            "10",
            "10",
            "10"
        ]
    },
    "secondDocument": {
        "~@i": "doc-002",
        "$$_entity_type_$$": [
            "Individual"
        ],
        "$$_entity_type_$$~.@ps": [
            "10"
        ],
        "FirstName": [
            "william"
        ],
        "FirstName~.@ps": [
            "10"
        ],
        "LastName": [
            "harley"
        ],
        "LastName~.@ps": [
            "10"
        ],
        "_mRuleUri": [
            "e§Individual§SameFirstName",
            "e§Individual§SameLastName",
            "e§Individual§SameFirstLastName"
        ],
        "_mRuleUri~.@ps": [
            "10",
            "10",
            "10"
        ]
    }
}

Response

The operation returns the standard explanation payload for both request modes.

In entity mode, the response includes:

summary
matchTokensSummary
applicableMatchGroups
versions
matchDocuments
candidatesDiscovery
rules
manualMatches

In raw match-document mode, the response includes:

summary
matchTokensSummary
applicableMatchGroups
rules

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

Example response: entity mode


{
  "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"
    ]
  },
"candidatesDiscovery": {
   "globalCandidatesFound": true,
  "matchGroupCandidateDiscoveries": {
    "configuration/entityTypes/HCP/matchGroups/RelevanceBasedRule": {
      "label": "Automatic on load Addresses",
      "candidatesFound": true
    },
    "configuration/entityTypes/HCP/matchGroups/RelevanceExactFirstName": {
      "label": "Will be bypassed",
      "candidatesFound": true
    }
  }
},
  "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"
          ]
        }
      }
    }
  }
}

Example response: raw match-document mode

{
  "summary": [
    "There are common match tokens. These inputs are considered as match candidates and will be checked according to the list of common applicable match rules."
  ],
  "matchTokensSummary": {
    "firstTotal": 3,
    "secondTotal": 3,
    "common": [
      "william",
      "harley"
    ]
  },
  "applicableMatchGroups": {
    "first": [
      "configuration/entityTypes/Individual/matchGroups/SameFirstName",
      "configuration/entityTypes/Individual/matchGroups/SameLastName",
      "configuration/entityTypes/Individual/matchGroups/SameFirstLastName"
    ],
    "second": [
      "configuration/entityTypes/Individual/matchGroups/SameFirstName",
      "configuration/entityTypes/Individual/matchGroups/SameLastName",
      "configuration/entityTypes/Individual/matchGroups/SameFirstLastName"
    ],
    "both": [
      "configuration/entityTypes/Individual/matchGroups/SameFirstName",
      "configuration/entityTypes/Individual/matchGroups/SameLastName",
      "configuration/entityTypes/Individual/matchGroups/SameFirstLastName"
    ],
    "bypassed": []
  },
  "versions": null,
  "matchDocuments": null,
  "candidatesDiscovery": null,
  "rules": {
    "configuration/entityTypes/Individual/matchGroups/SameFirstLastName": {
      "label": "Same first and last name",
      "matched": true,
      "matchedByDocuments": true
    }
  },
  "manualMatches": null
}

Response fields

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 evaluated inputs.
`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 evaluated inputs, 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. In raw match-document mode, the summary is still returned even when candidate-discovery details are unavailable.
`matchTokensSummary`	Summary of the tokens generated for both inputs. It displays the total number of tokens generated for both inputs from the request body according to the bypassed rules. Tokens generated by bypassed rules are not counted. It also shows 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` inputs 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`. In raw match-document mode, this field is `null`.
`candidatesDiscovery`	In entity mode, this field contains candidate-discovery results for the evaluated pair, including whether the inputs are considered match candidates and which match groups identified them as candidates. This section is returned even when `show=brief`. In raw match-document mode, this field is `null` because candidate discovery does not use full persisted-entity context.
`globalCandidatesFound`	Indicates whether the evaluated pair is considered a match candidate by any discovery method. Returns `true` if at least one match group determines candidacy.
`matchGroupCandidateDiscoveries`	Lists match groups and whether each one considers the evaluated pair a match candidate. Each key corresponds to a match-group URI.
`candidatesFound`	Indicates whether the specific match group considers the evaluated pair a match candidate.
`matched`	Indicates whether this match group considers the evaluated pair a match. The value is determined by document evaluation and candidate discovery when candidate-discovery data is available. The pair must be considered a match candidate for `matched` to be `true`.
`matchedByDocuments`	Indicates whether the evaluated inputs meet the match group's configured criteria based on match documents. This value does not include candidate discovery.
`versions`	Displays entity and match-document version details for persisted entities. In raw match-document mode, this field is `null`.
`matchDocuments`	Displays generated and database match-document details when they are available. In raw match-document mode, this field is `null`.
`rules`	Provides the rule-by-rule explanation of the evaluation result. Each key corresponds to a match-group URI.

ERROR - unresolved reference (1)

Unify and manage your data

Verifying matches

Supported request modes

Request

Request body

Example request

Response

Footer