Request

The Match Explanation API operation allows you to verify how a specific pair of entities — one from the Data Tenant (DT), one from the Customer Tenant (CT) — would be evaluated by DTSS match rules. This is useful when debugging unexpected match behavior or testing rule configuration.

Send either entity URIs or full entity payloads in the Match explanation POST request to your DTSS tenant. The response includes match rule details, tokens, evaluation logic, and match result.

POST {DTSSURL}/entities/_verifyMatches

Required headers:

Optional parameters:

Request body examples

You can use one of two formats:

URI-based:

{
  "dtEntity": "entities/0000I77",
  "ctEntity": "entities/0000BLK"
}

Full entity-based:

{
  "dtEntity": {
    "type": "configuration/entityTypes/Individual",
    "attributes": {
      "FirstName": [{ "value": "Ernest" }],
      "MiddleName": [{ "value": "Miller" }],
      "LastName": [{ "value": "H." }]
    }
  },
  "ctEntity": {
    "type": "configuration/entityTypes/Individual",
    "attributes": {
      "FirstName": [{ "value": "Ernest" }],
      "MiddleName": [{ "value": "M." }],
      "LastName": [{ "value": "Hemingway" }]
    }
  }
}

Response example

{
  "configuration/entityTypes/HCP/matchGroups/PersonByNPISuspect2": {
    "setAsNotMatch": false,
    "alreadySubscribed": false,
    "platformMatchRuleExplanation": {
      "matchTokens": {
        "first": {
          "foundInMatchTables": false,
          "tokens": ["0815092231"]
        },
        "second": {
          "foundInMatchTables": false,
          "tokens": ["0815092231"]
        },
        "intersection": {
          "tokens": ["0815092231"]
        }
      },
      "rule": {
        "and": [
          {
            "and": [
              {
                "exact": {
                  "NPI": true
                }
              }
            ]
          }
        ]
      },
      "matched": true
    }
  }
}

What the response tells you:

• Match rule being verified: The DTSS match rule used
• Match tokens: Tokens generated for both entities and their intersection
• Rule logic: Logical evaluation of match criteria
• Result: Indicates if entities matched ("matched": true)

For more information, see Match explanation in the Developer Portal.