> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Merge Contacts

> Merge two contacts into one. All data from the duplicate contact is moved to the primary contact, and the duplicate is deleted.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Body Parameters

**primary\_contact\_id** `string` *required*

The ID of the contact that will remain after the merge. Data from the duplicate will be merged into this contact.

**duplicate\_contact\_id** `string` *required*

The ID of the contact to merge and delete. All associated data (calls, conversations, memory) will be transferred to the primary contact.

### Response

**data** `object`

The merged contact object.

**data.id** `string`

Unique identifier for the merged contact (same as primary\_contact\_id).

**data.org\_id** `string`

Organization ID the contact belongs to.

**data.name** `string`

Contact's name (prefers primary, falls back to duplicate if primary is empty).

**data.metadata** `object`

Merged metadata from both contacts (primary takes precedence for conflicting keys).

**data.created\_at** `string`

ISO timestamp when the contact was created.

**data.updated\_at** `string`

ISO timestamp when the contact was last updated.

**errors** `null`

Error array (null on success).

### Merge Behavior

When merging contacts:

* **Identifiers**: All phone numbers, emails, and external IDs from the duplicate are added to the primary contact
* **Metadata**: Metadata objects are merged, with primary contact values taking precedence for conflicting keys
* **Name**: The primary contact's name is kept, unless it's empty (then the duplicate's name is used)
* **Calls**: All calls associated with the duplicate are reassigned to the primary contact
* **SMS Conversations**: All SMS conversations are reassigned to the primary contact
* **Contact Memory**: Memory data is merged (facts, recent messages, summaries) for each persona/agent. If both contacts have memory for the same persona, the data is intelligently combined

```json Response theme={null}
{
  "data": {
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "org_id": "11111111-2222-3333-4444-555555555555",
    "name": "John Doe",
    "metadata": {
      "source": "web_signup",
      "phone_verified": true,
      "email_verified": true
    },
    "created_at": "2025-07-20T10:30:00.000Z",
    "updated_at": "2025-07-22T16:30:00.000Z"
  },
  "errors": null
}
```

```json Error - Same Contact theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "Cannot merge a contact with itself"
    }
  ]
}
```

```json Error - Different Orgs theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "Cannot merge contacts from different orgs"
    }
  ]
}
```

```json Not Found theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Contact not found"
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.