Data quality API (BETA)

Scope requirements

This functionality is currently in beta. By participating in this beta, you agree to HubSpot's Developer Terms and Developer Beta Terms. Note that the functionality is still under active development and is subject to change based on testing and feedback.

Use the data quality API to retrieve details from HubSpot’s duplicate detection queue, which includes scored pairs with confidence scores. You can also retrieve custom deduplication rule definitions and results, so agents and integrators can act on HubSpot’s own signals rather than building independent candidate lists. Learn more about managing duplicate records on the HubSpot Knowledge Base.

Retrieve default deduplication results

To retrieve record pairs identified as potential duplicates via HubSpot’s default detection method, make a GET request to /crm/data-quality/objects/2027-03-beta/duplicates/default. The following query parameters are available to include in your request:

Parameter	Description
`objectType` required	The type of records to check for duplicates, such as contacts or companies.
`after`	A pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.
`limit`	The maximum number of pairs to return per page. Defaults to 25, maximum 200.
`objectId`	The unique identifier of the record to check for duplicates. Returns only pairs that contain this record.

The response will include the following properties:

Property	Type	Description
`results`	Array	A list of matching record pairs. This includes a `similarityScore` decimal property that ranges from 0 to 1 based on how closely the records match. `createdAt` and `updatedAt` timestamp properties are also included.
`paging`	Object	A cursor object that includes a `next.after` property that can be used for pagination.
`total`	Number	The total number of matching record pairs.

An example response is shown below:

{
  "results": [
    {
      "objectIds": ["12345", "67890"],
      "similarityScore": 0.94,
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-06-01T08:30:00Z"
    }
  ],
  "paging": {
    "next": {
      "after": "eyJza2lwIjoxMDB9",
      "link": "https://api.hubspot.com/crm/data-quality/2027-03-beta/..."
    }
  },
  "total": 1234
}

Retrieve custom deduplication rules

To retrieve existing custom duplicate rules defined for an account, make a GET request to /crm/data-quality/objects/2027-03-beta/duplicates/custom-rules. The following query parameters can be optionally included in your request:

Parameter	Description
`objectType`	The type of records to filter rules by, such as contacts or companies. If omitted, rules for all supported record types are returned.
`ruleId`	The ID of a specific rule to retrieve.

The response will include the following properties:

Property	Type	Description
`results`	Array	A list of custom rules. Each entry in the list includes the following sub-properties: `id`: the ID of the custom rule. `name`: the name of the rule. `objectType`: the object type that the rule applies to. `propertyNames`: the properties used to determine a match. `autoMergeEnabled`: whether matching records will be merged automatically. `createdAt`: an ISO 8601 timestamp denoting when the rule was created. `updatedAt`: an ISO 8601 timestamp denoting when the rule was last updated.
`paging`	Object	A cursor object that includes a `next.after` property that can be used for pagination.
`total`	Number	The total number of matching rules.

The code block below demonstrates an example response:

{
  "results": [
    {
      "id": "42",
      "name": "Duplicate contacts by email and phone",
      "objectType": "contacts",
      "propertyNames": ["email", "phone"],
      "autoMergeEnabled": false,
      "createdAt": "2026-01-10T09:00:00Z",
      "updatedAt": "2026-05-20T14:22:00Z"
    }
  ],
  "paging": {
    "next": {
      "after": "eyJza2lwIjoxMDB9",
      "link": "https://api.hubspot.com/crm/data-quality/2027-03-beta/..."
    }
  },
  "total": 5
}

You can also retrieve a specific custom rule by making a GET request to /crm/data-quality/objects/2027-03-beta/duplicates/custom-rules?ruleId={ruleId}, passing the ID of the rule as the ruleId query parameter.

Retrieve custom deduplication results

To retrieve groups of records that match custom duplicate rules, make a GET request to /crm/data-quality/objects/2027-03-beta/duplicates/custom-rules/groups, and append any applicable query parameters:

The objectType parameter is required in all requests.
In addition, at least one of the following parameters is also required based on what you’re filtering: ruleId, groupId or objectId.

Records are grouped when they share identical values for the properties defined in the rule. All available query parameters are detailed in the table below:

Parameter	Description
`objectType` required	The type of record to filter groups by, such as `contacts` or `companies`.
`after`	A pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.
`groupId`	The ID of a specific group to retrieve. Requires `ruleId`.
`limit`	The maximum number of groups to return per page. Defaults to 10, maximum 100. Only applies when listing groups by `ruleId`.
`objectId`	Returns all groups that contain this record.
`objectsPerGroup`	The maximum number of records to return per group. Defaults to 10, maximum 100.
`ruleId`	The ID of the custom duplicate rule to retrieve groups for. Required when using `groupId`.

The response will include the following properties:

Property	Type	Description
`results`	Array	A list of duplicate groups for a specific custom rule. Each entry in the list contains the following sub-properties: `id`: a string denoting the group ID. `ruleId`: the rule that produced the group. `objectType`: the type of records to check for duplicates, such as contacts or companies. `objectIds`: an array of 2 or more CRM object ID strings in the group. `matchedPropertyValues`: an object with the shared property values that triggered the match.
`paging`	Object	A cursor object that includes a `next.after` property that can be used for pagination.

An example response is shown in the code block below:

{
  "results": [
    {
      "id": "789",
      "ruleId": "42",
      "objectType": "contacts",
      "objectIds": ["101", "202", "303"],
      "matchedPropertyValues": {
        "email": "alice@example.com",
        "phone": "+1-555-0100"
      }
    }
  ],
  "paging": {
    "next": {
      "after": "eyJza2lwIjoxMDB9",
      "link": "https://api.hubspot.com/crm/data-quality/2027-03-beta/..."
    }
  }
}

Account & Settings

Automation

CMS

CRM

Marketing

Meetings

Querying data

Reporting

Revenue

Data quality API (BETA)

Retrieve default deduplication results

Retrieve custom deduplication rules

Retrieve custom deduplication results

​Retrieve default deduplication results

​Retrieve custom deduplication rules

​Retrieve custom deduplication results

Retrieve default deduplication results

Retrieve custom deduplication rules

Retrieve custom deduplication results