# Duplicate Detection API

Source: https://neondeerdata.com/docs/api/duplicate-detection/

Configure matching, review duplicate results, and manage authorized merge work.

## Access

This API requires an alpha invitation for your organization. Permissions determine which People or Companies results the connection can read and whether it may configure matching, start scans, request AI assessments, review results, or execute merges. See [permissions](https://neondeerdata.com/docs/api/permissions/).

## Matching and review

Read [capabilities and configuration](https://neondeerdata.com/docs/api/duplicate-detection/configuration/) first. Use [matching rules and previews](https://neondeerdata.com/docs/api/duplicate-detection/rules/) to create, edit, archive, restore, or preview custom rules. A preview is useful for inspection; creating a rule does not require one.

Inspect [matches and duplicate sets](https://neondeerdata.com/docs/api/duplicate-detection/sets/) and maintain [Not duplicate decisions](https://neondeerdata.com/docs/api/duplicate-detection/exclusions/). Request [AI assessments](https://neondeerdata.com/docs/api/duplicate-detection/ai-assessments/) when the connection and plan allow them.

Duplicate results return record references rather than CRM field values. Use your own Attio connection, or Attio's MCP connector, when you need those values. An AI assessment supports review; it does not establish that records should merge.

## Select records for a scan

A [scan](https://neondeerdata.com/docs/api/duplicate-detection/scans/) can check the whole object or a filtered selection:

| Selection mode | Records compared                                      |
| -------------- | ----------------------------------------------------- |
| `all`          | Every record of the selected object.                  |
| `of`           | Matching records against every record of that object. |
| `within`       | Only matching records against one another.            |

Read the scan-attribute list for the supported attributes, operators, option IDs, and related objects. Filters combine `and` and `or` groups. A related-record group requires one related record to satisfy the whole group. For example, when filtering companies by their deals, the same deal must satisfy both a stage condition and a value condition. Conditions require read permission and access to each object they read.

Previewing a selection does not start a scan or use the scan allowance. Counts come from the latest usable read of the object; `observed_at` identifies it. When the necessary data has not been read, counts are `null`, not zero.

Scan selections, duplicate-set filters, and lookup-row filters use different formats. Use the schema for the operation you are calling. For example, duplicate-set filters can compare a member's matched-rule count or permitted AI score and match rule IDs; those are not arbitrary CRM-field filters.

## Maintain named schedules

[Recurring schedules](https://neondeerdata.com/docs/api/duplicate-detection/schedules/) have their own names, timing, and optional record selection. A newly created API schedule starts paused unless you activate it. Read the organization's current time zone and configuration before creating or updating one.

A key can change schedules it created. Schedules created by a person in Neon Deer have different controls: a person-backed AI connection with permission can change recurrence or pause them, rather than replace all their settings. The reference describes those ownership rules.

A schedule checks its filter against the current Attio attributes before each run. Invalid conditions pause the schedule until corrected or cleared. Deleting a schedule stops future scans, not a scan already running. A scheduled scan never merges records.

## Merge deliberately

1. [Prepare a plan](https://neondeerdata.com/docs/api/duplicate-detection/merge-plans/) for the selected duplicate sets and the record to keep.
2. Follow the returned operation, then read the completed plan and review its effects and backup coverage.
3. Check that the organization and connection allow merge execution; otherwise, someone runs the plan in Neon Deer.
4. Execute with the current revision, digests, and access versions listed in the reference.
5. Inspect [execution progress and each item's result](https://neondeerdata.com/docs/api/duplicate-detection/executions/).

Preparing a plan does not merge records. Executing it changes Attio.

## Unmerge records from a backup

[Unmerging](https://neondeerdata.com/docs/api/duplicate-detection/recovery/) requires a saved pre-merge backup. Attio has no native unmerge, so Neon Deer reconstructs records with new Attio IDs. It restores supported attribute values, captured history, and references where Attio permits them. Read the recovery plan, then use its revision to start.

Unmerging also removes values the merge added to the kept record. Later edits remain, except where they set a value belonging to a merged-away record. Notes, tasks, and list entries stay on the merged record. Inspect the plan's omissions and follow-up work; unmerging cannot restore every detail exactly.

## Settings and safeguards

Permitted configuration writes take effect at the current resource version. Backup settings and permission to merge through the API or an AI app are managed in Neon Deer. See [configuration and safeguards](https://neondeerdata.com/docs/api/duplicate-detection/configuration/).