Merge two contacts into one

Merges a victim contact into a surviving contact. The victim's data (conversations, events,
attributes, tags, notes, segments, companies, and analytics) is re-parented to the survivor, and the
victim contact is then permanently deleted. The survivor keeps its own identifiers; any identifier the
survivor is missing (email, WhatsApp number, custom ID) is inherited from the victim when available.

⚠️ Warning: This action is irreversible. Once merged, the victim contact no longer exists.

Which contact survives?

• The contact in the URL path (polymorphic_contact_id) is the survivor — it is the one that remains.
• The contact referenced by victim_polymorphic_contact_id in the body is the victim — it is merged in and deleted.

How to Identify the Contacts

Both the survivor (path) and the victim (victim_polymorphic_contact_id) accept any of these identifier formats:

1. Customerly Contact ID (numeric): 29911301
2. Custom User ID (prefix cuid:): cuid:user_123
3. Custom Lead ID (prefix clid:): clid:lead_456
4. WhatsApp Number (prefix wa:): wa:+1234567890 (E.164 format)
5. Email Address (prefix uem: for users or lem: for leads): uem:[email protected]

Asynchronous Processing

Merges are processed asynchronously in the background. The endpoint validates the request, queues the
merge, and returns 202 Accepted with an empty body. Only one merge involving a given contact can run at
a time — requesting a merge while another one involving either contact is still in progress returns a
409 Conflict.

Example Requests

# Merge lead lead_456 into the user with Customerly ID 29911301
POST /contacts/29911301/merge
{ "victim_polymorphic_contact_id": "clid:lead_456" }

# Merge a contact identified by email into a contact identified by WhatsApp number
POST /contacts/wa:+1234567890/merge
{ "victim_polymorphic_contact_id": "uem:[email protected]" }