Newv4 is now live — a faster API, more channel support, and the headroom to scale. Explore v4
Contactsv4

Merge a contact

POST/contacts/{contactId}/merge

Collapses two auto-created contacts for the same person into one. The survivor is the {contactId} in the path; the source_contact_id in the body is absorbed into it. Every identity on the source is re-parented onto the survivor, tags are unioned, the survivor keeps its own name (falling back to the source's), and the source becomes a deprecated tombstone stamped with merged_into. Because chats and messages reference identities (not contacts), all conversations and timeline entries follow the moved identities automatically — nothing is rewritten or lost, and reads such as the survivor's timeline immediately reflect the merge. Idempotent: re-merging the same source into the same survivor returns 200; a source already merged into a different contact returns 409. Emits a contact.merged webhook event.

Path parameters

contactIdRequiredstring

Unique identifier of the contact, prefixed with ct_. Returned when you create a contact or by the List contacts endpoint.

Headers

AuthorizationRequiredstring

Your API key, sent as a bearer token: Authorization: Bearer <api_key>. Editing this stays in sync with the API key box on the right.

Bearer

Body parameters

JSON
source_contact_idRequiredstring

The contact to merge into the survivor, prefixed with ct_. Must differ from the path contact.

Returns

dataoptionalContact
idoptionalstring

Contact id (ct_...).

nameoptionalstring | null
created_atoptionalinteger
identitiesoptionalobject[]

Array of object

idoptionalstring
channel_typeoptionalstring
"blooio""twilio""whatsapp""whatsapp_business""rcs_business"
identifieroptionalstring
channel_idoptionalstring | null
created_atoptionalinteger

Response codes

200The merged survivor contact, now including the re-parented identities.
400The source equals the survivor, or an id is malformed.
401Your API key is missing or invalid. Pass it as a bearer token.
404No contact was found with the provided `contactId`.
409The source contact has already been merged into a different contact.
422Validation failed — one or more fields in the request are invalid or missing.

Sends a live request with your values and shows the real response below. Your key is stored only in this browser.

Request
curl -X POST https://api.blooio.com/v4/contacts/ct_a1b2c3d4/merge \  -H "Authorization: Bearer bl_live_..." \  -H "Content-Type: application/json" \  -d '{    "source_contact_id": "ct_01HZ0000000000000000000000"  }'
Body object
Response objectexample
{  "data": {    "id": "ct_a1b2c3d4",    "name": "Jane Doe",    "created_at": 0,    "identities": [      {        "id": "obj_a1b2c3d4",        "channel_type": "blooio",        "identifier": "+15551234567",        "channel_id": "ch_a1b2c3d4",        "created_at": 0      }    ]  }}