Skip to content
Home/
REST API Reference
/
/
Merge two contacts

Merge two contacts

Request

You can merge one contact into another. Both lead-into-user and user-into-user merges are supported: the source contact (from) may have a role of lead or user, and the destination contact (into) must have a role of user.

User-to-user merges

When you merge a user into another user, the source user's attribute values (standard and custom) are discarded and are not moved onto the target user. The target user keeps its own attribute values. Records associated with the source, such as conversations, notes, and tags, are still reassigned to the target.

Merging a user into another user requires the merge_users OAuth scope on your access token, in addition to the scope required for lead-into-user merges. Tokens without this scope receive a 401 Unauthorized when the source contact is a user.

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 410 Gone with a Link header pointing to the canonical (merged-into) contact.
  • 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.

Security
bearerAuth
Query
include_merge_historyboolean

Pass true to include the merge history of the resulting contact in the response. Only returned for contacts with a user role.

Default:false
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"Preview"
Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:Preview
Bodyapplication/json
fromstringrequired

The unique identifier for the contact to merge away from (the source contact). Can have a role of lead or user.

Example:"5d70dd30de4efd54f42fd526"
intostringrequired

The unique identifier for the contact to merge into (the destination contact). Must have a role of user.

Example:"5ba682d23d7cf92bef87bfd4"
skip_duplicate_validationboolean

When true, bypasses the check that the two contacts must be duplicates (matching email or phone), allowing non-duplicate contacts to be merged. Must be a JSON boolean; the string "true" does not bypass the check.

Default:false
Example:false
curl -i -X POST \
  'https://api.intercom.io/contacts/merge?include_merge_history=false' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "from": "6762f0d51bb69f9f2193bb7f",
    "into": "6762f0d51bb69f9f2193bb80"
  }'

Responses

successful

Bodyapplication/json
typestring

The type of object.

Example:"contact"
idstring

The unique identifier for the contact which is given by Intercom.

Example:"5ba682d23d7cf92bef87bfd4"
external_idstring or null

The unique identifier for the contact which is provided by the Client.

Example:"f3b87a2e09d514c6c2e79b9a"
workspace_idstring

The id of the workspace which the contact belongs to.

Example:"ecahpwf5"
rolestring

The role of the contact.

Example:"user"
emailstring

The contact's email.

Example:"joe@example.com"
email_domainstring

The contact's email domain.

Example:"example.com"
phonestring or null

The contacts phone.

Example:"+1123456789"
formatted_phonestring or null

The contacts phone number normalized to the E164 format

Example:"+1123456789"
namestring or null

The contacts name.

Example:"John Doe"
owner_idstring or null

The id of an admin that has been assigned account ownership of the contact.

Example:"321"
has_hard_bouncedboolean

Whether the contact has had an email sent to them hard bounce.

Example:true
marked_email_as_spamboolean

Whether the contact has marked an email sent to them as spam.

Example:true
unsubscribed_from_emailsboolean

Whether the contact is unsubscribed from emails.

Example:true
created_atinteger, (date-time)

(Unix timestamp in seconds) The time when the contact was created.

Example:1571672154
updated_atinteger, (date-time)

(Unix timestamp in seconds) The time when the contact was last updated.

Example:1571672154
signed_up_atinteger or null, (date-time)

(Unix timestamp in seconds) The time specified for when a contact signed up.

Example:1571672154
last_seen_atinteger or null, (date-time)

(Unix timestamp in seconds) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).

Example:1571672154
last_replied_atinteger or null, (date-time)

(Unix timestamp in seconds) The time when the contact last messaged in.

Example:1571672154
last_contacted_atinteger or null, (date-time)

(Unix timestamp in seconds) The time when the contact was last messaged.

Example:1571672154
last_email_opened_atinteger or null, (date-time)

(Unix timestamp in seconds) The time when the contact last opened an email.

Example:1571672154
last_email_clicked_atinteger or null, (date-time)

(Unix timestamp in seconds) The time when the contact last clicked a link in an email.

Example:1571672154
language_overridestring or null

A preferred language setting for the contact, used by Intercom as the language of Fin and the Messenger even if their browser has a different setting. Supports ISO 639-1 two-letter language codes. If an unsupported code is supplied, the field will be set to null.

Example:"en"
browserstring or null

The name of the browser which the contact is using.

Example:"Chrome"
browser_versionstring or null

The version of the browser which the contact is using.

Example:"80.0.3987.132"
browser_languagestring or null

The language set by the browser which the contact is using.

Example:"en-US"
osstring or null

The operating system which the contact is using.

Example:"Mac OS X"
android_app_namestring or null

The name of the Android app which the contact is using.

Example:"Intercom"
android_app_versionstring or null

The version of the Android app which the contact is using.

Example:"5.0.0"
android_devicestring or null

The Android device which the contact is using.

Example:"Pixel 3"
android_os_versionstring or null

The version of the Android OS which the contact is using.

Example:"10"
android_sdk_versionstring or null

The version of the Android SDK which the contact is using.

Example:"28"
android_last_seen_atinteger or null, (date-time)

(Unix timestamp in seconds) The time when the contact was last seen on an Android device.

Example:1571672154
ios_app_namestring or null

The name of the iOS app which the contact is using.

Example:"Intercom"
ios_app_versionstring or null

The version of the iOS app which the contact is using.

Example:"5.0.0"
ios_devicestring or null

The iOS device which the contact is using.

Example:"iPhone 11"
ios_os_versionstring or null

The version of iOS which the contact is using.

Example:"13.3.1"
ios_sdk_versionstring or null

The version of the iOS SDK which the contact is using.

Example:"13.3.1"
ios_last_seen_atinteger or null, (date-time)

(Unix timestamp in seconds) The last time the contact used the iOS app.

Example:1571672154
custom_attributesobject

The custom attributes which are set for the contact.

avatarobject or null
tagsobject or null(Contact Tags)

An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.

notesobject(Contact notes)

An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.

companiesobject(Contact companies)

An object with metadata about companies attached to a contact . Up to 10 will be displayed here. Use the url to get more.

locationobject(Contact Location)

An object containing location meta data about a Intercom contact.

social_profilesobject(Social Profile)

An object containing social profiles that a contact has.

merge_historyArray of objects or null(Merge History Item)

A list of contacts that were merged into this contact. Only included in the response when include_merge_history=true is passed as a query parameter. Only available for contacts with a user role.

enabled_push_messagingboolean or null

If the user has enabled push messaging.

Example:true
Response
{
  "type": "contact",
  "id": "6762f0d51bb69f9f2193bb80",
  "workspace_id": "this_is_an_id291_that_should_be_at_least_",
  "external_id": "70",
  "role": "user",
  "email": "joe@bloggs.com",
  "phone": null,
  "formatted_phone": null,
  "name": "Joe Bloggs",
  "avatar": null,
  "owner_id": null,
  "social_profiles": {
    "type": "list",
    "data": []
  },
  "has_hard_bounced": false,
  "marked_email_as_spam": false,
  "unsubscribed_from_emails": false,
  "created_at": 1734537429,
  "updated_at": 1734537430,
  "signed_up_at": 1734537429,
  "last_seen_at": null,
  "last_replied_at": null,
  "last_contacted_at": null,
  "last_email_opened_at": null,
  "last_email_clicked_at": null,
  "language_override": null,
  "browser": null,
  "browser_version": null,
  "browser_language": null,
  "os": null,
  "location": {
    "type": "location",
    "country": null,
    "region": null,
    "city": null,
    "country_code": null,
    "continent_code": null
  },
  "android_app_name": null,
  "android_app_version": null,
  "android_device": null,
  "android_os_version": null,
  "android_sdk_version": null,
  "android_last_seen_at": null,
  "ios_app_name": null,
  "ios_app_version": null,
  "ios_device": null,
  "ios_os_version": null,
  "ios_sdk_version": null,
  "ios_last_seen_at": null,
  "custom_attributes": {},
  "tags": {
    "type": "list",
    "data": [],
    "url": "/contacts/6762f0d51bb69f9f2193bb80/tags",
    "total_count": 0,
    "has_more": false
  },
  "notes": {
    "type": "list",
    "data": [],
    "url": "/contacts/6762f0d51bb69f9f2193bb80/notes",
    "total_count": 0,
    "has_more": false
  },
  "companies": {
    "type": "list",
    "data": [],
    "url": "/contacts/6762f0d51bb69f9f2193bb80/companies",
    "total_count": 0,
    "has_more": false
  },
  "opted_out_subscription_types": {
    "type": "list",
    "data": [],
    "url": "/contacts/6762f0d51bb69f9f2193bb80/subscriptions",
    "total_count": 0,
    "has_more": false
  },
  "opted_in_subscription_types": {
    "type": "list",
    "data": [],
    "url": "/contacts/6762f0d51bb69f9f2193bb80/subscriptions",
    "total_count": 0,
    "has_more": false
  },
  "utm_campaign": null,
  "utm_content": null,
  "utm_medium": null,
  "utm_source": null,
  "utm_term": null,
  "referrer": null,
  "enabled_push_messaging": null
}