How to merge contacts via API

When to use

• You have the same customer duplicated across two contacts (e.g., they came in through different channels) and want to combine them into one
• You are deduplicating your contact base through an integration
• You want to consolidate the history (conversations, messages, notes) of two contacts into a single record

Prerequisites

• Your API Key at hand — see How to find your API Key in Cloud Chat

• CLOUDCHAT_DOMAIN and ACCOUNT_ID

• The two contact ids to be merged — to find them, use the search described in How to query contacts, tickets and messages in real time via API

Endpoint

POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/actions/contact_merge

Headers

Request body

{
  "base_contact_id": 100,
  "mergee_contact_id": 250
}

How it works

When merging:

• All conversations, messages, notes, inboxes (contact_inboxes), CSAT responses and campaign events of the absorbed contact are moved to the base contact.

• For profile fields (name, email, phone_number, identifier, additional_attributes, custom_attributes), the base contact wins. Where the base contact is empty, the value from the absorbed contact is used.

• The absorbed contact (mergee_contact_id) is deleted at the end.

• Response 200 with the resulting base contact.

Request example

curl -X POST \
  'https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/actions/contact_merge' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{
    "base_contact_id": 100,
    "mergee_contact_id": 250
  }'

Common errors

Notes

• Create, update and delete individual contacts: How to create, update and delete contacts via API

• Find contact ids: How to query contacts, tickets and messages in real time via API

• Overview of all available APIs: Master Guide — How to access and operate Cloud Chat data via API