Intercom API (unofficial showcase)
POST/contacts/merge

Merge a lead into a user contact

Merges a contact with the lead role into a contact with the user role. Supply the source contact in from and the destination contact in into; set skip_duplicate_validation to true to merge contacts without a shared email or phone. The source contact is removed from the active contact list after the merge, so update stored IDs to the destination contact's ID.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 3 body fields
include_merge_historybooleanoptional
Set to true to include the resulting contact's merge history when it has a user role. Defaults to false when omitted.
Default:false
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Identifies the source and destination contacts for the merge.

fromstringrequired
The unique identifier for the contact to merge away from. Must be a lead.
intostringrequired
The unique identifier for the contact to merge into. Must be a user.
skip_duplicate_validationbooleanoptional
Set to `true` to merge two contacts that are not duplicates (they share no matching email or phone).

3 status codes
200Returns the resulting contact object after the merge.
enabled_push_messagingbooleanoptional
If the user has enabled push messaging.
typestringoptional
The type of object.
idstringoptional
The unique identifier for the contact which is given by Intercom.
external_idstringoptional
The unique identifier for the contact which is provided by the Client.
workspace_idstringoptional
The id of the workspace which the contact belongs to.
rolestringoptional
The role of the contact.
emailstringoptional
The contact's email.
email_domainstringoptional
The contact's email domain.
email_verifiedbooleanoptional
Whether the contact has proved they own their current email address. `true` only when this address was marked verified through the Contacts API (`email_verified: true` on create or update) and has not changed since; it becomes `false` again if the contact's email changes, until the new address is verified. Intercom reuses a lead with a verified email when it later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead.
phonestringoptional
The contacts phone.
namestringoptional
The contacts name.
owner_idstringoptional
The id of an admin that has been assigned account ownership of the contact.
has_hard_bouncedbooleanoptional
Whether the contact has had an email sent to them hard bounce.
marked_email_as_spambooleanoptional
Whether the contact has marked an email sent to them as spam.
unsubscribed_from_emailsbooleanoptional
Whether the contact is unsubscribed from emails.
created_atintegeroptional
(Unix timestamp in seconds) The time when the contact was created.
updated_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last updated.
signed_up_atintegeroptional
(Unix timestamp in seconds) The time specified for when a contact signed up.
last_seen_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
last_replied_atintegeroptional
(Unix timestamp in seconds) The time when the contact last messaged in.
last_contacted_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last messaged.
last_email_opened_atintegeroptional
(Unix timestamp in seconds) The time when the contact last opened an email.
last_email_clicked_atintegeroptional
(Unix timestamp in seconds) The time when the contact last clicked a link in an email.
language_overridestringoptional
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
browserstringoptional
The name of the browser which the contact is using.
browser_versionstringoptional
The version of the browser which the contact is using.
browser_languagestringoptional
The language set by the browser which the contact is using.
osstringoptional
The operating system which the contact is using.
android_app_namestringoptional
The name of the Android app which the contact is using.
android_app_versionstringoptional
The version of the Android app which the contact is using.
android_devicestringoptional
The Android device which the contact is using.
android_os_versionstringoptional
The version of the Android OS which the contact is using.
android_sdk_versionstringoptional
The version of the Android SDK which the contact is using.
android_last_seen_atintegeroptional
(Unix timestamp in seconds) The time when the contact was last seen on an Android device.
ios_app_namestringoptional
The name of the iOS app which the contact is using.
ios_app_versionstringoptional
The version of the iOS app which the contact is using.
ios_devicestringoptional
The iOS device which the contact is using.
ios_os_versionstringoptional
The version of iOS which the contact is using.
ios_sdk_versionstringoptional
The version of the iOS SDK which the contact is using.
ios_last_seen_atintegeroptional
(Unix timestamp in seconds) The last time the contact used the iOS app.
custom_attributesobjectoptional
The custom attributes which are set for the contact.
avatarobjectoptional
tagsobjectoptional
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.
notesobjectoptional
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.
companiesobjectoptional
An object with metadata about companies attached to a contact . Up to 10 will be displayed here. Use the url to get more.
locationobjectoptional
An object containing location meta data about a Intercom contact.
social_profilesobjectoptional
An object containing social profiles that a contact has.
merge_historyarray<MergeHistoryItem>optional
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.
400Returned when the merge request fails validation, including when the contacts do not meet the merge requirements.

One documented failure

  • invalid_merge

    Contacts can only be merged when they are duplicates (matching email or phone). Pass skip_duplicate_validation=true to override this check.

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 400 is returned when the merge request fails validation, including when the contacts do not meet the merge requirements. A 401 is returned when the request is unauthorized. The from field must identify a lead and the into field must identify a user; set skip_duplicate_validation to true only when you intend to merge contacts without a shared email or phone.