Merge contacts

Merge a duplicate contact into another one, the same way Merge contacts works on the Contacts page. Use it when POST /contacts or GET /contacts show two contacts for the same person.

POST/contacts/merge

Authentication

This endpoint authenticates with your API key sent in the X-API-Key header (ek_live_... format). You can manage your API keys from the Dev Tools section of the dashboard.

The merge cannot be undone: the duplicate is deleted once its data has moved to the surviving contact.

Request body

ParameterTypeRequiredDescription
survivor_idStringRequiredUUID of the contact that stays.
loser_idStringRequiredUUID of the duplicate. It is merged into the survivor and deleted.
field_choicesObjectOptionalWhich value wins when both contacts have one, per field: an object mapping the field name to survivor or loser, e.g. {"email": "loser"}. Accepts first_name, last_name, email and collected_data.<key> for a key inside collected_data (e.g. collected_data.rut). Fields not listed keep the survivor's value.

Example request

bash
curl -X POST "https://api.eclecticlabs.com/api/external/v2/contacts/merge" \
  -H "X-API-Key: ek_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "survivor_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "loser_id": "9c1e6d2a-0b7f-4c3d-8a52-7e1f0d4b9a11",
    "field_choices": { "email": "loser" }
  }'

Example response

json
{
  "success": true,
  "survivor_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Notes

  • The duplicate's conversations, messages and history move to the survivor. The survivor fills its empty fields from the duplicate, and tags and custom data are combined.
  • The duplicate's email and phone are kept as aliases of the survivor, so future messages and API calls carrying them resolve to the surviving contact.
  • Possible errors: 400 (validation, or a merge that is not allowed: the same contact twice, or a test contact with a real one), 401 (invalid or missing API key), 404 (a contact does not exist in your business), 500 (internal error).