---
title: "Merge two records"
method: POST
path: "/v2/objects/{object}/records/merge"
tags: ["Records"]
---

# Merge two records

`POST /v2/objects/{object}/records/merge`

Merges two records of the same object together. Where both records have a value for the same attribute, the primary record's value takes precedence.

Merging produces a **new** record, so the `new_record_id` returned will match neither of the records supplied in the request. Both of the original records are marked as merged and can no longer be read or written.

Large merges are completed asynchronously. A `200` response means the merged record is readable immediately. A `202` response means the merge has been accepted but is still being applied, and reading the merged record will return a `404` with the `merge_in_progress` error code until it completes.

This endpoint is not idempotent. Because both original records are marked as merged, repeating the same request returns `404`.

This endpoint is rate limited to 5 requests per second.

This endpoint is in beta. We will aim to avoid breaking changes, but small updates may be made as we roll out to more users.

Required scopes: `record_permission:read-write`, `object_configuration:read`.

## Path parameters

- `object` string, required — A UUID or slug of the object both records belong to.

## Request body

- object
  - `data` object, required
    - `primary_record_id` string, uuid, required — The ID of the record to keep values from. Where both records have a value for the same attribute, the primary record's value takes precedence.
    - `secondary_record_id` string, uuid, required — The ID of the record to merge into the primary record. Its values are only kept where the primary record has no value for that attribute.

## Response `200`

Success

- object — Success
  - `data` object, required
    - `new_record_id` string, uuid, required — The ID of the merged record. This is a new ID, which will usually match neither of the records supplied in the request.

## Other responses

- `202` — Accepted. The merge has been committed but is still being applied, so the merged record is not yet readable.
- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found

## Changes

> 16 revisions in range; 9 could not be searched.

- **2026-07-31** `d2bfa505e42c` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/attio/apis/attio-api/changes/v2/objects/:object/records/merge/post.md)

---

[API](https://skmtc.dev/attio/apis/attio-api.md) · [All operations](https://skmtc.dev/attio/apis/attio-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/attio/attio-api/revisions/191597d35978/schema)