---
title: Merge duplicate records with the API | Lightfield
description: 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](/help/accounts/merge-duplicates/index.md) 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](/help/settings/api-keys/index.md) 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.

Terminal window

```
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](/api/resources/merge/methods/mergeAccounts/index.md) 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](/using-the-api/idempotency/index.md).

## 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](/api/resources/merge/methods/getMerge/index.md):

Terminal window

```
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](/api/resources/account/methods/retrieve/index.md) before updating your integration’s stored IDs:

Terminal window

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

- [Contacts](/api/resources/merge/methods/mergeContacts/index.md).
- [Opportunities](/api/resources/merge/methods/mergeOpportunities/index.md).
- [Custom object records](/api/resources/merge/methods/mergeObjectValues/index.md).

For a refused request, inspect its error and follow [Errors](/using-the-api/errors/index.md) before retrying. Do not switch the primary and duplicate IDs as a retry strategy.