Search for potential matches in Data Tenants (DT)

Learn how to use the DTSS API to search for potential matches among entities within the Data Tenant (DT).

Use this DTSS operation to identify potential matches for one or more entities within the same Data Tenant (DT). This operation is useful for validating entity uniqueness or detecting redundancy before further processing.

Note: The match rules defined under the MANUAL_MATCH section of the Synchronization Configuration will be used for the search, if they exist.

Request

Use this endpoint to search for potential matches in the DT:

POST {DTSSURL}/entities/_matchesForCtEntities

Headers


Name	Required	Description
`CustomerTenant`	Yes	Customer Tenant ID
`DataTenant`	Yes	Data Tenant ID
`SearchMetadata`	No	Determines which metadata format to return: `CT` – Convert DT match result into CT metadata `DT` – Return result using DT metadata `AUTO` – Uses subscription attribute `searchMatchesCtMetadata` to determine format

Optional parameters

You can include the following optional parameters to customize the match behavior:


Name	Location	Type	Value	Description
max	query	integer	For example, 100	A positive integer that defines the maximum number of entities returned in the response.
skipAllImportedEntities	query	boolean	True False Default is false.	If true, hides potential matches from the DT that are already subscribed to by entities in the CT. Default is false.
options	query	string	`sendHidden` is disabled by default. When enabled, the entity's JSON response includes hidden attributes. `ovOnly` returns only attribute values with the ov=true flag. `nonOvOnly` returns only attribute values with the ov=false flag. If a nested or reference attribute has ov=true but its sub-attributes have ov=false, those sub-attributes are not included in the response. `searchByOv` is disabled by default. When enabled, search and sort operations are performed only on attributes where ov=true.	Comma-separated list of different options which affect entity's JSON content in the response
filter	query	string	The format for the filter query parameter is: filter=({Condition Type}[AND/OR {Condition Type}]*)	Enables filtering the entities based on a condition
sources	query	filter	For example, configuration/sources/LNKD	Specifies the crosswalks to use when searching for entities in the Data Tenant

Request body

Submit a JSON array of entities—either as URIs or full entity objects—to find matches in the Data Tenant.

Note: Don't include a label field in the request body, or the entities will be rejected.

URI-only example:

[
  "entities/0000I77"
]

Full object example:

[
  {
    "uri": "entities/0000I77",
    "type": "configuration/entityTypes/Individual",
    "attributes": {
      "FirstName": [
        {
          "type": "configuration/entityTypes/Individual/attributes/FirstName",
          "ov": true,
          "value": "Ernest",
          "uri": "entities/0000I77/attributes/FirstName/241"
        }
      ],
      "MiddleName": [
        {
          "type": "configuration/entityTypes/Individual/attributes/MiddleName",
          "ov": true,
          "value": "E.",
          "uri": "entities/0000I77/attributes/MiddleName/1vl"
        }
      ]
    }
  }
]

Response

The response returns a JSON array of matched DT entities. Entities that are explicitly marked as "not a match" are excluded.

[
  {
    "index": 0,
    "object": {
      "configuration/entityTypes/Individual/matchGroups/PersonByFullNameInES": [
        {
          "uri": "entities/0000I77",
          "type": "configuration/entityTypes/Individual",
          "createdBy": "admin",
          "createdTime": 1369070358438,
          "updatedTime": 1369070358438,
          "startDate": 35154000000,
          "roles": ["configuration/roles/Client"],
          "attributes": {
            "FirstName": [
              {
                "type": "configuration/entityTypes/Individual/attributes/FirstName",
                "ov": true,
                "value": "Ernest",
                "uri": "entities/0000I77/attributes/FirstName/241"
              }
            ],
            "LastName": [
              {
                "type": "configuration/entityTypes/Individual/attributes/LastName",
                "ov": true,
                "value": "Fusco",
                "uri": "entities/0000I77/attributes/LastName/2CH"
              }
            ]
          }
        }
      ]
    }
  }
]

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

Unify and manage your data