Skip to main content

Merging user profiles

How to manually merge two user profiles, so a user's information is tied to a single profile.

Written by Adisa Narula

Sometimes the same person ends up with two user profiles in Intercom. For example, they signed up twice with different user IDs, or an integration created a second profile for them. Their conversations, tickets and notes are then split across both profiles.
​

You can now merge one user into another, so everything about that person lives on a single profile. You can do this from the Inbox, or with the REST API (Intercom's API for reading and writing data over HTTP).

Who this applies to: Teammates with the Can merge a user into another user permission (Inbox), and developers using an OAuth app (an app authenticated with an OAuth access token, rather than a static API key) with the Merge users scope (API).
​

Looking to merge a lead into a user instead? See Merge lead and user profiles
​

What happens when you merge two users

A merge always has two sides:

  • The duplicate (source): the profile that gets merged away. It's permanently deleted.

  • The surviving user (target): the profile that's kept.

What moves to the surviving user

  • Conversations and tickets, including their replies, notes, attachments and ratings

  • Notes on the profile

  • Tags

  • Companies

  • Phone calls

  • Messages sent to the user, and their opens, clicks and replies

  • Survey progress and goal progress

  • Mobile push device registrations

  • Links to connected helpdesks and integrations

What doesn't move

  • Attributes. The surviving user keeps its own standard and custom attribute values, and the duplicate's values are discarded. Before you confirm, the merge preview shows every value that will be dropped. If you need to keep one, copy it onto the surviving user before or after the merge.

  • WhatsApp conversation data. The merge still goes ahead, but the duplicate's WhatsApp data is removed along with it.

  • SMS conversation threads
    ​

Important: Merging is permanent. You can't undo it.

Before you start: who can merge users


In the Inbox

Merging users needs a new teammate permission, Can merge a user into another user.

  • It's off by default, and no one gets it automatically when it launches. Teammates with full access already have it.

  • An admin can turn it on for a teammate by editing their permissions in Settings > Workspace > Teammates.

  • It's available on Full, Support, Engage, Convert and Lite seats.

Merging a lead into a user doesn't need this permission and works the same as before.
​

Through the API

API requests to merge two users need both:

  1. An OAuth access token. Legacy API keys aren't supported for user merges.

  2. The Merge users scope, in addition to the scope your app already uses to write contacts (such as Read and write users).
    ​

Note: Merging users through the API is currently in Preview. It's not available to every workspace automatically. Contact us to request access. The Merge users scope only appears in the Developer Hub once access has been turned on for your workspace.

How to merge two users in the Inbox

  1. Open a conversation with the user you want to keep.

  2. In the conversation details sidebar, find Duplicate user data. It lists any profiles Intercom has detected as duplicates of this user.

  3. Next to the duplicate user, click Merge User Into User.

  4. Review the preview. It shows how many conversations, tickets, notes, tags and phone calls will move, and which attribute values from the duplicate will be discarded. Nothing changes until you confirm.

  5. Click Merge.

5. Click Merge. The duplicate profile is deleted immediately, its conversations, tickets, and notes now appear on the surviving user's profile, and you're returned to the conversation you started from.

Conversation details sidebar showing a user profile card with the user's name, company, type, and email address flagged as a detected duplicate, plus a Merge User Into User button.

Merge user into user preview dialog with a confirmation message that the duplicate profile will be permanently deleted and merged into the surviving user, and a table comparing Duplicate, User, and User after merge values for fields including name, email, phone, session counts, conversations, and notes.

What else should I know before merging?

  • The profile you're viewing when you click Merge User Into User is always the one that survives. To keep the other profile instead, open a conversation belonging to that profile and merge from there.

  • Only detected duplicates are listed. Two users count as duplicates when they share an email address or phone number.

  • If you don't have the permission, the button is disabled and shows "You don't currently have permission to perform user merges." Ask an admin to grant it.
    ​


How to merge two users with the API

User merges use the existing Merge a contact endpoint, called with the Preview API version header (Intercom's release stage for early-access API changes) — this Preview API version is separate from the merge preview described above. See the developer docs.

Preview the merge first (recommended)

POST /contacts/merge/preview shows what a merge would do without changing anything:

curl https://api.intercom.io/contacts/merge/preview \
  -X POST \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Intercom-Version: Preview" \
  -H "Content-Type: application/json" \
  -d '{ "from": "<duplicate_contact_id>", "into": "<surviving_contact_id>" }'

The response tells you whether the merge is allowed ("allowed"), and if not, why ("reasons"). It also includes a "summary" of the records that will move and the attribute values that will be discarded.

Merge

POST /contacts/merge performs the merge:

curl https://api.intercom.io/contacts/merge \
  -X POST \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Intercom-Version: Preview" \
  -H "Content-Type: application/json" \
  -d '{ "from": "<duplicate_contact_id>", "into": "<surviving_contact_id>" }'

"from" is the duplicate user, which is deleted.

"into" is the user you want to keep.

A successful merge returns the surviving contact, including its id, and the merged data (conversations, tickets, notes, tags) now associated with it. For example: { "type": "contact", "id": "", "email": "...", ... }

What are the limitations of merging users?

  • Merges are permanent. There's no way to unmerge.

  • Attributes aren't combined. The surviving user's attribute values are kept and the duplicate's are discarded.

  • Some contacts can't be merged: users who contacted you through Facebook, users with Telegram conversations (as the duplicate), and mailing-list contacts.

  • WhatsApp and SMS conversation data on the duplicate isn't moved.

  • In the Inbox, users must share an email address or phone number. To merge users that don't, use the API with skip_duplicate_validation.

  • The API is in Preview, so the request and response format may change before it reaches a numbered API version.

💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts

Related Articles
Did this answer your question?