> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Data quality API (BETA)

> Use the data quality API to retrieve duplicate CRM records from your account, along with existing custom deduplication rules you've created.

> **Scope requirements**

> [!WARNING]
>
> This functionality is currently in beta. By participating in this beta, you agree to HubSpot's [Developer Terms](https://legal.hubspot.com/developer-terms) and [Developer Beta Terms](https://legal.hubspot.com/developerbetaterms). 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](https://knowledge.hubspot.com/records/manage-duplicate-records).

## 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:

```json theme={null}
{
  "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: <ul><li>`id`: the ID of the custom rule.</li><li>`name`: the name of the rule.</li><li>`objectType`: the object type that the rule applies to.</li><li>`propertyNames`: the properties used to determine a match.</li><li>`autoMergeEnabled`: whether matching records will be merged automatically.</li><li>`createdAt`: an ISO 8601 timestamp denoting when the rule was created.</li><li>`updatedAt`: an ISO 8601 timestamp denoting when the rule was last updated.</li></ul> |
| `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:

```json theme={null}
{
  "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: <ul><li>`id`: a string denoting the group ID.</li><li>`ruleId`: the rule that produced the group.</li><li> `objectType`: the type of records to check for duplicates, such as contacts or companies.</li><li>`objectIds`: an array of 2 or more CRM object ID strings in the group.</li><li>`matchedPropertyValues`: an object with the shared property values that triggered the match.</li></ul> |
| `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:

```json theme={null}
{
  "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/..."
    }
  }
}
```