> For the complete documentation index, see [llms.txt](https://docs.zero.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zero.inc/developers/api/merging-records.md).

# Merging Records

Merging keeps one record — the primary — and folds the others into it. Everything related to the duplicates (deals, emails, calendar events, tasks, notes, comments, files, invoices and the rest) is repointed at the primary, and the duplicates are archived rather than deleted.

There is an endpoint for each of contacts, companies and deals. They behave identically; only the field naming the primary changes.

## Merge Contacts

```
POST /api/contacts/merge
```

### Request Body

| Field       | Type      | Required | Description                                                  |
| ----------- | --------- | -------- | ------------------------------------------------------------ |
| `contactId` | string    | Yes      | ID of the contact to keep (the primary record).              |
| `mergeIds`  | string\[] | Yes      | IDs of the contacts to merge into the primary, then archive. |

### Example

```bash
curl -X POST "https://api.zero.inc/api/contacts/merge" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "PRIMARY_CONTACT_UUID",
    "mergeIds": ["DUPLICATE_CONTACT_UUID_1", "DUPLICATE_CONTACT_UUID_2"]
  }'
```

### Behavior

* Field values (title, company, location, social handles, phone, type, etc.) are taken from the primary contact when set, otherwise the first non-empty value from the merged contacts is used.
* List memberships, owners, and custom properties are combined across all contacts.
* All related records (deals, email threads, calendar events, LinkedIn threads and connections, custom activities, tasks, notes, comments, files, invoices, issues, and analytics events) are repointed from the merged contacts to the primary contact.
* Each merged contact is archived and stamped with `mergedToId` (the primary contact's ID) and `mergedAt`.

### Response

```json
{
  "success": true,
  "data": {
    "id": "PRIMARY_CONTACT_UUID"
  }
}
```

The `data` object is the primary contact that the others were merged into.

## Merge Companies

```
POST /api/companies/merge
```

As above, with `companyId` naming the primary.

### Example

```bash
curl -X POST "https://api.zero.inc/api/companies/merge" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "PRIMARY_COMPANY_UUID",
    "mergeIds": ["DUPLICATE_COMPANY_UUID_1"]
  }'
```

## Merge Deals

```
POST /api/deals/merge
```

As above, with `dealId` naming the primary.

### Example

```bash
curl -X POST "https://api.zero.inc/api/deals/merge" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dealId": "PRIMARY_DEAL_UUID",
    "mergeIds": ["DUPLICATE_DEAL_UUID_1"]
  }'
```

## Notes

* All three require a Bearer token and only touch records in your workspace.
* Merging cannot be undone through the API. The duplicates survive as archived records, but their relations have already moved to the primary.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zero.inc/developers/api/merging-records.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.