$ curl https://api.intercom.io/contacts/merge \\\n-X POST \\\n-H 'Authorization:Bearer <Your access token>' \\\n-H 'Accept:application/json' -d \\\n-H 'Content-Type:application/json' -d \\\n\n{\n \"from\": \"5d70dd30de4efd54f42fd526\",\n \"into\": \"5ba682d23d7cf92bef87bfd4\"\n}\nHTTP/1.1 404 FOUND\n{\n \"type\": \"error.list\",\n \"request_id\": \"9a3d0816-9707-4598-977e-c009ba630148\",\n \"errors\": [\n {\n \"code\": \"not_found\",\n \"message\": \"Contact Not Found\"\n }\n ]\n}\nHTTP/1.1 400 UNPROCESSABLE ENTITY\n{\n \"type\": \"error.list\",\n \"request_id\": \"0019c4t1derm7namdon0\",\n \"errors\": [\n {\n \"code\": \"invalid_merge\",\n \"message\": \"Merging can only be performed on a lead into a user\"\n }\n ]\n}\nYou can merge a contact with a role of lead into a contact with a role of user.
What happens upon a contact being merged?
The contact that's specified as from will be deleted after being merged into the contact specified as into. Attributes that don't exist on the contact specified as into will be copied over.
Merged contacts are not retrievable via the API
Once a merge is completed, the source contact (from) is permanently removed from the active contact list. This means:
- GET /contacts/:id — Requesting the source contact by its original ID will return a
404 Not Founderror. - POST /contacts/search — The source contact will not appear in search results, including queries filtered by
updated_at. - GET /contacts — The source contact will not appear in list results.
Only the target contact (into) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge. You can subscribe to the contact.merged webhook to be notified when merges occur.
| Parameter | Type | Required | Description |
|---|---|---|---|
| from | String | Yes | The unique identifier for the contact to merge away from. Must be a lead. |
| into | String | Yes | The unique identifier for the contact to merge into. Must be a user. |
This will return a Contact model for the contact who's been merged into.