Scans and selection previews
Choose records to scan, inspect supported attributes, preview a selection, and follow or cancel a scan.
The APIs on this page require alpha access for your organization. App availability and API access are separate. Check access and permissions.
List scans
GET /v1/deduplication/runs
Lists duplicate scans, one page at a time. status can be sent more than once to match any of them.
Requires dedupe:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: list_dedupe_scans. 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" |
|
status |
query | No | array of "queued", "running", "completed", "partial", "failed", "canceled" |
Repeat this query parameter for multiple values. |
schedule_id |
query | No | string | |
created_at_from |
query | No | string (date-time) | |
created_at_before |
query | No | string (date-time) | |
sort |
query | No | "-created_at", "created_at" |
|
limit |
query | No | integer | |
cursor |
query | No | 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 |
array of object | Yes | |
data[].object |
"deduplication_run" |
Yes | |
data[].id |
string | Yes | |
data[].version |
string | Yes | |
data[].object_type |
"companies", "people" |
Yes | |
data[].connection_id |
string | Yes | |
data[].status |
"queued", "running", "completed", "partial", "failed", "canceled" |
Yes | |
data[].reason_code |
"stopped_early", "plan_allowance", "max_records_reached", "canceled_by_request", "consent_revoked", "access_ended", "disconnected", "provider_unreachable", "provider_error", "records_changed", "service_interrupted", "related_unavailable", "failed" or null |
Yes | |
data[].schedule_id |
string or null | Yes | |
data[].created_at |
string (date-time) | Yes | |
data[].ended_at |
string (date-time) or null | Yes | |
data[].coverage |
object | Yes | |
data[].coverage.records_read |
integer or null | Yes | |
data[].coverage.complete |
boolean | Yes | |
data[].coverage.rules |
array of object | Yes | |
data[].coverage.rules[].rule_id |
string | Yes | |
data[].coverage.rules[].state |
"complete", "resolving", "incomplete", "skipped" |
Yes | |
data[].coverage.published_at |
string (date-time) or null | Yes | |
data[].results_ready |
boolean | Yes | |
data[].client_reference |
string or null | Yes | |
pagination |
object | Yes | |
pagination.next_cursor |
string or null | 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.
Start scan
POST /v1/deduplication/runs
Starts a scan for duplicates with the current matching configuration; send its version as expected_configuration_version. The scan runs in the background: poll the returned operation until it finishes, then read the duplicate sets. To scan part of the object, send selection with a mode. of: compare matching records with every record; within: compare matching records only with each other. Conditions combine with and/or groups, and a related group follows a record reference, such as a person's company, where one related record must meet the whole group. List the scan attributes for what each attribute takes, and preview the selection to see how many records it matches. Conditions also need the dedupe:read scope and access to every object they read. An AI assessment after the scan (after_scan) also needs the dedupe:ai:assess scope, AI access for this key, a unit budget and a deadline.
Requires dedupe:scan. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: start_dedupe_scan. 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 |
|---|---|---|---|---|
connection_id |
JSON body | Yes | string | |
object_type |
JSON body | Yes | "companies", "people" |
|
expected_configuration_version |
JSON body | Yes | string | |
first_scan |
JSON body | No | "fast", "complete" |
|
ai_assessment |
JSON body | No | object | |
ai_assessment.mode |
Within the JSON value | Within this object | "none" |
When ai_assessment.mode is "none". |
ai_assessment.mode |
Within the JSON value | Within this object | "after_scan" |
When ai_assessment.mode is "after_scan". |
ai_assessment.budget |
Within the JSON value | Within this object | object | When ai_assessment.mode is "after_scan". |
ai_assessment.budget.max_assessment_units |
Within the JSON value | Within this object | integer | When ai_assessment.mode is "after_scan". |
ai_assessment.expires_at |
Within the JSON value | Within this object | string (date-time) | When ai_assessment.mode is "after_scan". An RFC 3339 time in UTC ending in Z, for example 2026-11-04T18:30:00Z. A fraction of a second is rounded up to the next whole second. |
limits |
JSON body | No | object | |
limits.max_records |
Within the JSON value | No | integer | |
limits.max_paid_units |
Within the JSON value | No | 0 |
|
client_reference |
JSON body | No | string | |
selection |
JSON body | No | object | |
selection.mode |
Within the JSON value | Within this object | "all" |
When selection.mode is "all". |
selection.mode |
Within the JSON value | Within this object | "of", "within" |
When selection.mode is "of", "within". |
selection.where |
Within the JSON value | Within this object | DedupeScanConditionGroup | When selection.mode is "of", "within". |
selection.where.type |
Within the JSON value | Within this object | "and", "or" |
When selection.mode is "of", "within". |
selection.where.conditions |
Within the JSON value | Within this object | array of object or DedupeScanConditionGroup | When selection.mode is "of", "within". |
selection.where.conditions[].type |
Within the JSON value | Within this object | "attribute" |
When selection.mode is "of", "within". When selection.where.conditions[].type is "attribute". |
selection.where.conditions[].attribute |
Within the JSON value | Within this object | string | When selection.mode is "of", "within". When selection.where.conditions[].type is "attribute". When selection.where.conditions[].type is "related". |
selection.where.conditions[].operator |
Within the JSON value | Within this object | "is", "is_not", "contains", "not_contains", "lt", "lte", "gt", "gte", "any_of", "none_of", "empty", "not_empty" |
When selection.mode is "of", "within". When selection.where.conditions[].type is "attribute". |
selection.where.conditions[].value |
Within the JSON value | No | string or number or boolean or array of string | When selection.mode is "of", "within". When selection.where.conditions[].type is "attribute". |
selection.where.conditions[].type |
Within the JSON value | Within this object | "related" |
When selection.mode is "of", "within". When selection.where.conditions[].type is "related". |
selection.where.conditions[].object |
Within the JSON value | Within this object | string | When selection.mode is "of", "within". When selection.where.conditions[].type is "related". |
selection.where.conditions[].where |
Within the JSON value | Within this object | DedupeScanConditionGroup | When selection.mode is "of", "within". When selection.where.conditions[].type is "related". |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
202 |
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.id |
string | Yes | |
data.object |
"operation" |
Yes | |
data.version |
string | Yes | |
data.resource_id |
string | Yes | |
data.resource_type |
string | Yes | |
data.status |
"pending", "succeeded", "failed", "canceled", "needs_attention" |
Yes | |
data.terminal |
boolean | Yes | |
data.created_at |
string (date-time) | Yes | |
data.ended_at |
string (date-time) or null | Yes | |
data.reason_code |
string or null | Yes | |
data.replayed |
true |
No | |
data.operation_type |
"scan_cancel", "ai_assessment", "ai_assessment_cancel", "review_update", "exclusion_create", "exclusion_update", "scheduled_batch_create", "scheduled_batch_update", "scheduled_batch_cancel", "scheduled_run_cancel", "scheduled_record_cancel", "schedule_create", "schedule_update", "webhook_endpoint_create", "webhook_endpoint_update", "webhook_secret_rotate", "endpoint_verification", "webhook_replay", "merge_rebuild", "scheduled_batch_transfer", "webhook_endpoint_transfer" |
Yes | When data.operation_type is "scan_cancel", "ai_assessment", "ai_assessment_cancel", "review_update", "exclusion_create", "exclusion_update", "scheduled_batch_create", "scheduled_batch_update", "scheduled_batch_cancel", "scheduled_run_cancel", "scheduled_record_cancel", "schedule_create", "schedule_update", "webhook_endpoint_create", "webhook_endpoint_update", "webhook_secret_rotate", "endpoint_verification", "webhook_replay", "merge_rebuild", "scheduled_batch_transfer", "webhook_endpoint_transfer". |
data.action_metadata |
object | Yes | |
data.action_metadata.resource_version |
string | Yes | |
data.action_metadata.allowed_actions |
array of string | Yes | |
data.operation_type |
"merge_execute", "merge_cancel" |
Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.action_metadata.execute_not_before |
string (date-time) | Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.action_metadata.authorization_expires_at |
string (date-time) | Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.operation_type |
"plan_prepare", "plan_revision_prepare", "retry_plan_prepare" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.plan_revision |
string | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.effects_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.preview_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.recovery_coverage_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement |
object | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.scope |
"organization_baseline" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.mode |
"api_key_allowed", "not_allowed" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.policy_version |
string | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.grant_evaluation |
"at_execution" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.reason_code |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_state |
"unauthorized", "authorized", "rejected", "invalidated", "expired" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.operation_type |
"review_bulk_update", "exclusion_bulk_create" |
Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results |
array of object | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].index |
integer | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].outcome |
"succeeded", "failed" |
Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref |
object | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref.id |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref.version |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error |
object | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.code |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.message |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.param |
string | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.operation_type |
"scan", "scan_continue" |
Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child |
object | Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.state |
"not_requested", "pending_admission", "admitted", "skipped", "failed" |
Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.reason_code |
string or null | Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.ai_run_id |
string | No | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.ai_operation_id |
string | No | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.operation_url |
string (uri) | No | When data.operation_type is "scan", "scan_continue". |
Accepted work can continue after the request returns. Follow its returned status or operation until it finishes; accepting work does not mean every item succeeded. See operation status.
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.
Get scan
GET /v1/deduplication/runs/{scan_id}
Gets one scan: its status, how many records it covered and whether its results are ready.
Requires dedupe:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: get_dedupe_scan. 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 |
|---|---|---|---|---|
scan_id |
path | 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_run" |
Yes | |
data.id |
string | Yes | |
data.version |
string | Yes | |
data.object_type |
"companies", "people" |
Yes | |
data.connection_id |
string | Yes | |
data.status |
"queued", "running", "completed", "partial", "failed", "canceled" |
Yes | |
data.reason_code |
"stopped_early", "plan_allowance", "max_records_reached", "canceled_by_request", "consent_revoked", "access_ended", "disconnected", "provider_unreachable", "provider_error", "records_changed", "service_interrupted", "related_unavailable", "failed" or null |
Yes | |
data.schedule_id |
string or null | Yes | |
data.created_at |
string (date-time) | Yes | |
data.ended_at |
string (date-time) or null | Yes | |
data.coverage |
object | Yes | |
data.coverage.records_read |
integer or null | Yes | |
data.coverage.complete |
boolean | Yes | |
data.coverage.rules |
array of object | Yes | |
data.coverage.rules[].rule_id |
string | Yes | |
data.coverage.rules[].state |
"complete", "resolving", "incomplete", "skipped" |
Yes | |
data.coverage.published_at |
string (date-time) or null | Yes | |
data.results_ready |
boolean | Yes | |
data.client_reference |
string or null | Yes |
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, unknown_parameter. |
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.
List scan attributes
GET /v1/deduplication/scan-attributes
Lists the attributes a scan's conditions can use on an object, with the operators each one takes, the options of a select or status attribute (a condition names an option by its id), and the objects a record reference points at. Send object to list a related object's attributes for a related condition group; this key needs access to that object too. Archived attributes, and kinds of attribute conditions can't read, are left out.
Requires dedupe:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: list_dedupe_scan_attributes. 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 | Yes | "companies", "people" |
|
object |
query | No | 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_scan_attributes" |
Yes | |
data.object_type |
"companies", "people" |
Yes | |
data.attributes_of |
string | Yes | |
data.attributes |
array of object | Yes | |
data.attributes[].slug |
string | Yes | |
data.attributes[].title |
string | Yes | |
data.attributes[].kind |
"text", "number", "date", "timestamp", "checkbox", "option", "record" |
Yes | |
data.attributes[].multiselect |
boolean | Yes | |
data.attributes[].operators |
array of "is", "is_not", "contains", "not_contains", "lt", "lte", "gt", "gte", "any_of", "none_of", "empty", "not_empty" |
Yes | |
data.attributes[].targets |
array of string or null | Yes | |
data.attributes[].options |
array of object or null | Yes | |
data.attributes[].options[].id |
string | Yes | Alternative 1. |
data.attributes[].options[].title |
string | 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.
Preview scan
POST /v1/deduplication/scan-previews
Counts how many records a scan's selection matches, and how many records a scan would compare them with, before you start it. It starts no scan, uses none of your scan allowance and changes nothing. The counts come from the latest read of the object that holds every attribute the conditions use; observed_at says when that read finished. When no such read exists the status is not_read and the counts are null: the scan itself reads them.
Requires dedupe:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: preview_dedupe_scan. 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 |
|---|---|---|---|---|
connection_id |
JSON body | Yes | string | |
object_type |
JSON body | Yes | "companies", "people" |
|
selection |
JSON body | Yes | object | |
selection.mode |
Within the JSON value | Within this object | "all" |
When selection.mode is "all". |
selection.mode |
Within the JSON value | Within this object | "of", "within" |
When selection.mode is "of", "within". |
selection.where |
Within the JSON value | Within this object | DedupeScanConditionGroup | When selection.mode is "of", "within". |
selection.where.type |
Within the JSON value | Within this object | "and", "or" |
When selection.mode is "of", "within". |
selection.where.conditions |
Within the JSON value | Within this object | array of object or DedupeScanConditionGroup | When selection.mode is "of", "within". |
selection.where.conditions[].type |
Within the JSON value | Within this object | "attribute" |
When selection.mode is "of", "within". When selection.where.conditions[].type is "attribute". |
selection.where.conditions[].attribute |
Within the JSON value | Within this object | string | When selection.mode is "of", "within". When selection.where.conditions[].type is "attribute". When selection.where.conditions[].type is "related". |
selection.where.conditions[].operator |
Within the JSON value | Within this object | "is", "is_not", "contains", "not_contains", "lt", "lte", "gt", "gte", "any_of", "none_of", "empty", "not_empty" |
When selection.mode is "of", "within". When selection.where.conditions[].type is "attribute". |
selection.where.conditions[].value |
Within the JSON value | No | string or number or boolean or array of string | When selection.mode is "of", "within". When selection.where.conditions[].type is "attribute". |
selection.where.conditions[].type |
Within the JSON value | Within this object | "related" |
When selection.mode is "of", "within". When selection.where.conditions[].type is "related". |
selection.where.conditions[].object |
Within the JSON value | Within this object | string | When selection.mode is "of", "within". When selection.where.conditions[].type is "related". |
selection.where.conditions[].where |
Within the JSON value | Within this object | DedupeScanConditionGroup | When selection.mode is "of", "within". When selection.where.conditions[].type is "related". |
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_scan_preview" |
Yes | |
data.object_type |
"companies", "people" |
Yes | |
data.mode |
"all", "of", "within" |
Yes | |
data.status |
"complete", "not_read" |
Yes | |
data.matching_records |
integer or null | Yes | |
data.comparison_records |
integer or null | Yes | |
data.observed_at |
string (date-time) or null | Yes |
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, unknown_parameter. |
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.
Continue scan
POST /v1/deduplication/runs/{scan_id}/continue
Continues a partial scan from where it stopped. Send the scan's version as expected_version, then poll the returned operation.
Requires dedupe:scan. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: continue_dedupe_scan. 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 |
|---|---|---|---|---|
scan_id |
path | Yes | string | |
expected_version |
JSON body | Yes | string | |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
202 |
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.id |
string | Yes | |
data.object |
"operation" |
Yes | |
data.version |
string | Yes | |
data.resource_id |
string | Yes | |
data.resource_type |
string | Yes | |
data.status |
"pending", "succeeded", "failed", "canceled", "needs_attention" |
Yes | |
data.terminal |
boolean | Yes | |
data.created_at |
string (date-time) | Yes | |
data.ended_at |
string (date-time) or null | Yes | |
data.reason_code |
string or null | Yes | |
data.replayed |
true |
No | |
data.operation_type |
"scan_cancel", "ai_assessment", "ai_assessment_cancel", "review_update", "exclusion_create", "exclusion_update", "scheduled_batch_create", "scheduled_batch_update", "scheduled_batch_cancel", "scheduled_run_cancel", "scheduled_record_cancel", "schedule_create", "schedule_update", "webhook_endpoint_create", "webhook_endpoint_update", "webhook_secret_rotate", "endpoint_verification", "webhook_replay", "merge_rebuild", "scheduled_batch_transfer", "webhook_endpoint_transfer" |
Yes | When data.operation_type is "scan_cancel", "ai_assessment", "ai_assessment_cancel", "review_update", "exclusion_create", "exclusion_update", "scheduled_batch_create", "scheduled_batch_update", "scheduled_batch_cancel", "scheduled_run_cancel", "scheduled_record_cancel", "schedule_create", "schedule_update", "webhook_endpoint_create", "webhook_endpoint_update", "webhook_secret_rotate", "endpoint_verification", "webhook_replay", "merge_rebuild", "scheduled_batch_transfer", "webhook_endpoint_transfer". |
data.action_metadata |
object | Yes | |
data.action_metadata.resource_version |
string | Yes | |
data.action_metadata.allowed_actions |
array of string | Yes | |
data.operation_type |
"merge_execute", "merge_cancel" |
Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.action_metadata.execute_not_before |
string (date-time) | Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.action_metadata.authorization_expires_at |
string (date-time) | Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.operation_type |
"plan_prepare", "plan_revision_prepare", "retry_plan_prepare" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.plan_revision |
string | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.effects_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.preview_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.recovery_coverage_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement |
object | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.scope |
"organization_baseline" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.mode |
"api_key_allowed", "not_allowed" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.policy_version |
string | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.grant_evaluation |
"at_execution" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.reason_code |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_state |
"unauthorized", "authorized", "rejected", "invalidated", "expired" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.operation_type |
"review_bulk_update", "exclusion_bulk_create" |
Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results |
array of object | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].index |
integer | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].outcome |
"succeeded", "failed" |
Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref |
object | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref.id |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref.version |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error |
object | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.code |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.message |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.param |
string | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.operation_type |
"scan", "scan_continue" |
Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child |
object | Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.state |
"not_requested", "pending_admission", "admitted", "skipped", "failed" |
Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.reason_code |
string or null | Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.ai_run_id |
string | No | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.ai_operation_id |
string | No | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.operation_url |
string (uri) | No | When data.operation_type is "scan", "scan_continue". |
Accepted work can continue after the request returns. Follow its returned status or operation until it finishes; accepting work does not mean every item succeeded. See operation status.
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.
Cancel scan
POST /v1/deduplication/runs/{scan_id}/cancel
Stops an unfinished scan this key started. Send the scan's version as expected_version. Needs no extra scope, but the key must still have access to the object.
Requires an active connection. Access to existing work is checked against the connection that started it.
MCP action: cancel_dedupe_scan. 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 |
|---|---|---|---|---|
scan_id |
path | Yes | string | |
expected_version |
JSON body | Yes | string | |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
202 |
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.id |
string | Yes | |
data.object |
"operation" |
Yes | |
data.version |
string | Yes | |
data.resource_id |
string | Yes | |
data.resource_type |
string | Yes | |
data.status |
"pending", "succeeded", "failed", "canceled", "needs_attention" |
Yes | |
data.terminal |
boolean | Yes | |
data.created_at |
string (date-time) | Yes | |
data.ended_at |
string (date-time) or null | Yes | |
data.reason_code |
string or null | Yes | |
data.replayed |
true |
No | |
data.operation_type |
"scan_cancel", "ai_assessment", "ai_assessment_cancel", "review_update", "exclusion_create", "exclusion_update", "scheduled_batch_create", "scheduled_batch_update", "scheduled_batch_cancel", "scheduled_run_cancel", "scheduled_record_cancel", "schedule_create", "schedule_update", "webhook_endpoint_create", "webhook_endpoint_update", "webhook_secret_rotate", "endpoint_verification", "webhook_replay", "merge_rebuild", "scheduled_batch_transfer", "webhook_endpoint_transfer" |
Yes | When data.operation_type is "scan_cancel", "ai_assessment", "ai_assessment_cancel", "review_update", "exclusion_create", "exclusion_update", "scheduled_batch_create", "scheduled_batch_update", "scheduled_batch_cancel", "scheduled_run_cancel", "scheduled_record_cancel", "schedule_create", "schedule_update", "webhook_endpoint_create", "webhook_endpoint_update", "webhook_secret_rotate", "endpoint_verification", "webhook_replay", "merge_rebuild", "scheduled_batch_transfer", "webhook_endpoint_transfer". |
data.action_metadata |
object | Yes | |
data.action_metadata.resource_version |
string | Yes | |
data.action_metadata.allowed_actions |
array of string | Yes | |
data.operation_type |
"merge_execute", "merge_cancel" |
Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.action_metadata.execute_not_before |
string (date-time) | Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.action_metadata.authorization_expires_at |
string (date-time) | Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.operation_type |
"plan_prepare", "plan_revision_prepare", "retry_plan_prepare" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.plan_revision |
string | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.effects_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.preview_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.recovery_coverage_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement |
object | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.scope |
"organization_baseline" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.mode |
"api_key_allowed", "not_allowed" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.policy_version |
string | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.grant_evaluation |
"at_execution" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.reason_code |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_state |
"unauthorized", "authorized", "rejected", "invalidated", "expired" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.operation_type |
"review_bulk_update", "exclusion_bulk_create" |
Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results |
array of object | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].index |
integer | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].outcome |
"succeeded", "failed" |
Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref |
object | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref.id |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref.version |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error |
object | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.code |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.message |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.param |
string | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.operation_type |
"scan", "scan_continue" |
Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child |
object | Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.state |
"not_requested", "pending_admission", "admitted", "skipped", "failed" |
Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.reason_code |
string or null | Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.ai_run_id |
string | No | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.ai_operation_id |
string | No | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.operation_url |
string (uri) | No | When data.operation_type is "scan", "scan_continue". |
Accepted work can continue after the request returns. Follow its returned status or operation until it finishes; accepting work does not mean every item succeeded. See operation status.
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.