Merge duplicate records with the API

Work with CRM data

Choose the record to keep, merge a duplicate into it, and check the merge result.

Use a merge when two records represent the same account, contact, opportunity or custom object. Read Merge duplicates first for the product rules and what happens to linked data. API merges apply without a review card.

Before you begin

Create an API key with the read scope for the selected record type, plus the update and delete scopes required by the merge endpoint. For the account walkthrough below, grant accounts:read, accounts:update and accounts:delete. Retrieve both records and confirm which ID to keep before sending the write.

For opportunities, both records must belong to the same account. For custom objects, both must belong to the object type named in the request path.

Merge two accounts

Use primaryId for the account you want to keep and duplicateId for the duplicate. The primary keeps its ID; the duplicate is soft-deleted.

curl https://api.lightfield.app/v1/accounts/merge \
  -X POST \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: merge-northwind-001" \
  -d '{
    "primaryId": "acc_primary",
    "duplicateId": "acc_duplicate",
    "fieldResolutions": {
      "industry": "primary"
    }
  }'

The industry example selects the primary record’s value for a custom field with that slug. Use the account merge reference for all resolution options and the full response schema.

Merge requests require Idempotency-Key. Choose a new key for each intended merge and reuse it only when retrying that same merge. See Idempotency.

Check the result

The response includes the merge ID, retained record and any non-fatal warnings. This excerpt shows the fields to inspect:

{
  "merge": { "id": "merge_northwind", "status": "cleanup_pending" },
  "primary": { "id": "acc_primary" },
  "summary": { "warnings": [] }
}

Review summary.warnings and set MERGE_ID to merge.id. Use it with Get merge status:

curl "https://api.lightfield.app/v1/merges/$MERGE_ID" \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01"

Check status before treating cleanup as complete:

cleanup_pending: check this same merge ID again; do not start another merge.
done: retrieve the retained record and compare the fields you resolved and the relationship IDs your integration uses.
failed: preserve the merge ID and response for investigation; do not reverse the primary and duplicate IDs or start another merge as a recovery step.

Retrieve the retained account before updating your integration’s stored IDs:

curl "https://api.lightfield.app/v1/accounts/acc_primary" \
  -H "Authorization: Bearer $LIGHTFIELD_API_KEY" \
  -H "Lightfield-Version: 2026-03-01"

Merge another record type

Use the endpoint for the type you are merging:

For a refused request, inspect its error and follow Errors before retrying. Do not switch the primary and duplicate IDs as a retry strategy.