Skip to content
Home/
REST API Reference
/
/
Merge a lead and a user

Merge a lead and a user

Request

You can merge a contact with a role of lead into a contact with a role of 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 a 404 Not Found error.
  • 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
Headers
Intercom-Versionstring(intercom_version)

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

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

The unique identifier for the contact to merge away from. Must be a lead.

Example:"5d70dd30de4efd54f42fd526"
intostringrequired

The unique identifier for the contact to merge into. Must be a user.

Example:"5ba682d23d7cf92bef87bfd4"
curl -i -X POST \
  https://api.intercom.io/contacts/merge \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.11' \
  -d '{
    "from": "667d60ac8a68186f43bafdbb",
    "into": "667d60ac8a68186f43bafdbc"
  }'

Responses

successful

Bodyapplication/json
typestring

The type of object.

Example:"contact"
idstringrequired

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

Example:"5ba682d23d7cf92bef87bfd4"
external_idstring or nullrequired

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

Example:"f3b87a2e09d514c6c2e79b9a"
workspace_idstringrequired

The id of the workspace which the contact belongs to.

Example:"ecahpwf5"
rolestringrequired

The role of the contact.

Example:"user"
emailstringrequired

The contact's email.

Example:"joe@example.com"
email_domainstring

The contact's email domain.

Example:"example.com"
phonestring or nullrequired

The contacts phone.

Example:"+1123456789"
formatted_phonestring or null

The contacts phone number normalized to the E164 format

Example:"+1123456789"
namestring or nullrequired

The contacts name.

Example:"John Doe"
owner_idinteger or nullrequired

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

Example:123
has_hard_bouncedbooleanrequired

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

Example:true
marked_email_as_spambooleanrequired

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

Example:true
unsubscribed_from_emailsbooleanrequired

Whether the contact is unsubscribed from emails.

Example:true
created_atinteger, (date-time)required

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

Example:1571672154
updated_atinteger, (date-time)required

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

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

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

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

(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)required

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

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

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

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

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

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

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

Example:1571672154
language_overridestring or nullrequired

A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.

Example:"en"
browserstring or nullrequired

The name of the browser which the contact is using.

Example:"Chrome"
browser_versionstring or nullrequired

The version of the browser which the contact is using.

Example:"80.0.3987.132"
browser_languagestring or nullrequired

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

Example:"en-US"
osstring or nullrequired

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 nullrequired
tagsobject(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 containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.

locationobject(Contact Location)required

An object containing location metadata about a Intercom contact.

social_profilesobject(Social Profile)required

An object containing social profiles that a contact has.

Response
{
  "type": "contact",
  "id": "667d60ac8a68186f43bafdbc",
  "workspace_id": "this_is_an_id260_that_should_be_at_least_",
  "external_id": "70",
  "role": "user",
  "email": "joe@bloggs.com",
  "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": 1719492780,
  "updated_at": 1719492780,
  "signed_up_at": 1719492780,
  "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/667d60ac8a68186f43bafdbc/tags",
    "total_count": 0,
    "has_more": false
  },
  "notes": {
    "type": "list",
    "data": [],
    "url": "/contacts/667d60ac8a68186f43bafdbc/notes",
    "total_count": 0,
    "has_more": false
  },
  "companies": {
    "type": "list",
    "data": [],
    "url": "/contacts/667d60ac8a68186f43bafdbc/companies",
    "total_count": 0,
    "has_more": false
  },
  "opted_out_subscription_types": {
    "type": "list",
    "data": [],
    "url": "/contacts/667d60ac8a68186f43bafdbc/subscriptions",
    "total_count": 0,
    "has_more": false
  },
  "opted_in_subscription_types": {
    "type": "list",
    "data": [],
    "url": "/contacts/667d60ac8a68186f43bafdbc/subscriptions",
    "total_count": 0,
    "has_more": false
  },
  "utm_campaign": null,
  "utm_content": null,
  "utm_medium": null,
  "utm_source": null,
  "utm_term": null,
  "referrer": null
}