Configuration and safeguards

The APIs on this page require alpha access for your organization. App availability and API access are separate. Check access and permissions.

Capabilities

GET /v1/deduplication/capabilities

Lists the objects, matching rules, filter fields, operators and allowances this key can use. Read it first to learn what the other deduplication calls accept. Each object names the connection a scan runs through, and its configuration_version is the expected_configuration_version to send when you start a scan.

Requires dedupe:read. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: get_dedupe_capabilities. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
object_type	query	No	"companies", "people"

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"deduplication_capabilities"	Yes
data.objects	array of object	Yes
data.objects[].provider	"attio"	Yes
data.objects[].object_type	"companies", "people"	Yes
data.objects[].connection_id	string	Yes
data.objects[].full_object_scan	boolean	Yes
data.objects[].configuration_version	string	Yes
data.objects[].filter_fields	array of object	Yes
data.objects[].filter_fields[].field	"matched_rule_count", "ai_score", "rule_id"	Yes
data.objects[].filter_fields[].type	"number", "rule"	Yes
data.objects[].filter_fields[].operators	array of string	Yes
data.objects[].filter_fields[].field_ids	array of string	Yes
data.input_ranges	object	Yes
data.input_ranges.list_limit	object	Yes
data.input_ranges.list_limit.min	integer	Yes
data.input_ranges.list_limit.max	integer	Yes
data.input_ranges.list_limit.default	integer	Yes
data.input_ranges.repeated_query_values	object	Yes
data.input_ranges.repeated_query_values.max	integer	Yes
data.input_ranges.filter_predicates	object	Yes
data.input_ranges.filter_predicates.min	integer	Yes
data.input_ranges.filter_predicates.max	integer	Yes
data.input_ranges.filter_text_length	object	Yes
data.input_ranges.filter_text_length.max	integer	Yes
data.input_ranges.filter_rule_ids	object	Yes
data.input_ranges.filter_rule_ids.max	integer	Yes
data.input_ranges.bulk_items	object	Yes
data.input_ranges.bulk_items.min	integer	Yes
data.input_ranges.bulk_items.max	integer	Yes
data.input_ranges.note_length	object	Yes
data.input_ranges.note_length.max	integer	Yes
data.input_ranges.client_reference_length	object	Yes
data.input_ranges.client_reference_length.max	integer	Yes
data.allowances	object	Yes
data.allowances.scans_per_month	object or null	Yes
data.allowances.scans_per_month.included	integer	Yes	Alternative 1.
data.allowances.scans_per_month.used	integer	Yes	Alternative 1.
data.allowances.scans_per_month.resets_at	string (date-time)	Yes	Alternative 1.

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request, invalid_cursor.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
412	One of: version_conflict.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Configuration

GET /v1/deduplication/configuration

Gets the current matching configuration. Send its version as expected_version when you change the configuration, and an object's version as expected_configuration_version when you start a scan. The important and protected attributes, the maximum set size and the cancellation window (merge_hold_seconds) are shown here and can be changed with the settings change. Backups, domain redirect checks, whether AI scoring may include related records and whether merges may run through the API or an AI app are changed only in Neon Deer, on the Duplicate detection page the organization's apps list gives as app_url.

Requires dedupe:read. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: get_dedupe_configuration. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
object_type	query	No	"companies", "people"

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"deduplication_configuration"	Yes
data.version	string	Yes
data.ignore_common_values_default	integer	Yes
data.maximum_set_size	integer or null	Yes
data.objects	array of object	Yes
data.objects[].object_type	"companies", "people"	Yes
data.objects[].version	string	Yes
data.objects[].similarity	"low", "medium", "high", "very_high", "extreme"	Yes
data.objects[].merge_hold_seconds	integer	Yes
data.objects[].important_field_ids	array of string	Yes
data.objects[].protected_field_ids	array of string	Yes
data.objects[].field_references_withheld	boolean	Yes
data.objects[].automatic_ai_assessment	boolean	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request, invalid_cursor.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
412	One of: version_conflict.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Change settings

PATCH /v1/deduplication/configuration

Changes an object's similarity, its automatic AI assessment and its standard rules: switches a rule on or off, sets whether Attio checks new and changed records with it, its number for ignoring very common values, and the values it ignores. Also sets an object's important and protected attributes, the organization's maximum set size (sets with more records are held for review instead of merged; turning it off keeps the number), the cancellation window before a merge starts, Review sets larger than, and the organization's own number for ignoring very common values, which every rule on its default follows. Rule ids come from the matching rules list. Values you send for a rule to ignore are never returned; the matching rules list shows how many it has. Send the configuration's version as expected_version; a setting you leave out stays as it is. Turning automatic AI assessment on also needs the dedupe:ai:assess scope, and the plan must include it. Changing the cancellation window, Review sets larger than or protected attributes needs a grant over both objects. Backups, domain redirect checks, whether AI scoring may include related records and whether merges may run through the API or an AI app are changed only in Neon Deer. What this replaces is not kept, so it can't be undone.

Requires dedupe:config:write. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: update_dedupe_configuration. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
expected_version	JSON body	Yes	string
objects	JSON body	No	object
objects.companies	Within the JSON value	No	object
objects.companies.similarity	Within the JSON value	No	"low", "medium", "high", "very_high", "extreme"
objects.companies.automatic_ai_assessment	Within the JSON value	No	boolean
objects.companies.rules	Within the JSON value	No	object
objects.companies.automatic_checks	Within the JSON value	No	object
objects.companies.important_field_ids	Within the JSON value	No	array of string
objects.companies.protected_field_ids	Within the JSON value	No	array of string
objects.people	Within the JSON value	No	object
objects.people.similarity	Within the JSON value	No	"low", "medium", "high", "very_high", "extreme"
objects.people.automatic_ai_assessment	Within the JSON value	No	boolean
objects.people.rules	Within the JSON value	No	object
objects.people.automatic_checks	Within the JSON value	No	object
objects.people.important_field_ids	Within the JSON value	No	array of string
objects.people.protected_field_ids	Within the JSON value	No	array of string
ignore_common_values_default	JSON body	No	integer
maximum_set_size	JSON body	No	object
maximum_set_size.enabled	Within the JSON value	Within this object	true	Alternative 1.
maximum_set_size.records	Within the JSON value	No	integer	Alternative 1.
maximum_set_size.enabled	Within the JSON value	Within this object	false	Alternative 2.
cancellation_window	JSON body	No	object
cancellation_window.enabled	Within the JSON value	Within this object	true	Alternative 1.
cancellation_window.seconds	Within the JSON value	No	integer	Alternative 1.
cancellation_window.enabled	Within the JSON value	Within this object	false	Alternative 2.
review_sets_larger_than	JSON body	No	object
review_sets_larger_than.enabled	Within the JSON value	Within this object	true	Alternative 1.
review_sets_larger_than.records	Within the JSON value	No	integer	Alternative 1.
review_sets_larger_than.enabled	Within the JSON value	Within this object	false	Alternative 2.
request_key	Header: Idempotency-Key	Yes	string

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"deduplication_configuration_change"	Yes
data.object_type	"companies", "people"	No
data.version	string	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
412	One of: version_conflict.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Change set columns

PATCH /v1/deduplication/set-columns

Chooses the Attio attributes shown as extra columns when people in your organization review duplicate sets of an object in Neon Deer, in order. Send the configuration's version as expected_version and the whole list; an empty list shows none. Each person's own column order and hidden columns stay theirs. What this replaces is not kept, so it can't be undone.

Requires dedupe:config:write. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: update_dedupe_set_columns. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
expected_version	JSON body	Yes	string
object_type	JSON body	Yes	"companies", "people"
field_ids	JSON body	Yes	array of string
request_key	Header: Idempotency-Key	Yes	string

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"deduplication_configuration_change"	Yes
data.object_type	"companies", "people"	No
data.version	string	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
412	One of: version_conflict.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

Restore standard rules

POST /v1/deduplication/standard-rules/restore

Puts an object's standard matching rules back to how they ship: which are on, whether Attio checks new and changed records with each, their numbers for ignoring very common values, and the values they ignore. Custom rules are not changed. Send the configuration's version as expected_version. What this replaces is not kept, so it can't be undone.

Requires dedupe:config:write. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: restore_dedupe_standard_rules. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

Parameters

Name	Send in	Required	Type or allowed values	Notes
expected_version	JSON body	Yes	string
object_type	JSON body	Yes	"companies", "people"
request_key	Header: Idempotency-Key	Yes	string

Response

HTTP status	Result
200	The requested result. Asynchronous work returns an operation to poll.

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

Response field	Type	Required in object	Notes
data	object	Yes
data.object	"deduplication_configuration_change"	Yes
data.object_type	"companies", "people"	No
data.version	string	Yes

Errors

HTTP status	Meaning
400	One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	The current permissions, plan or policy do not allow this request.
404	One of: not_found.
409	The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying.
410	The requested resource or retained recovery data has expired.
412	One of: version_conflict.
413	One of: request_too_large.
422	A field, filter or selection cannot be used for this request.
423	One of: organization_reopening.
428	One of: customer_agreement_required.
429	One of: rate_limited.
503	One of: service_unavailable.

See errors and recovery and safe retries before repeating a write.

The public OpenAPI document lists generally available API families. Alpha operations may not appear in that document; their request and response fields are listed on this page. Use the API Playground to inspect a real response with your connection's access.