Skip to content
Home/
REST API Reference
/
/
Preview a contact merge

Preview a contact merge

Request

Preview the result of merging one contact into another without applying the merge. This is a read-only dry run: it reports whether the merge is allowed and, if so, exactly what would change, without modifying any data.

Send the same from and into contact IDs you would pass to Merge two contacts. As with the merge endpoint, from may have a role of lead or user, and into must have a role of user. You can optionally pass custom_attribute_names to include specific custom attributes in the previewed attribute changes.

  • When allowed is true, the response contains a summary: every attribute change (with the resulting value on the surviving contact) and, for each object type, two counts — from, how many are on the source contact and would move to the destination, and into, how many the destination already has. Counts are reported for conversations, tickets, phone calls, notes, and tags. conversations counts non-ticket conversations only; tickets are reported separately under tickets, and phone_calls is present only for phone-channel merges.
  • When allowed is false, the response contains reasons. Each reason has a stable code you can branch on and a human-readable message you can display.
Previewing non-duplicate contacts

By default a merge requires the two contacts to share an identifier (email or phone). Set skip_duplicate_validation to true to preview a merge of contacts that don't, the same rule the merge endpoint enforces.

When allowed is false, reasons[].code is one of:

codemeaning
source_same_as_targetThe source contact (from) and the destination contact (into) are the same contact. A contact can't be merged into itself.
invalid_merge_role_pairThe from/into roles aren't mergeable. into must be a user.
no_shared_identifierThe contacts share no email or phone. Set skip_duplicate_validation to preview anyway.
facebook_userFacebook contacts can't be merged.
external_lead_channel_not_allowedThe source is an external-channel lead that isn't eligible for merging.
mailing_listContacts created from a mailing list can't be merged.
user_to_leadinto is a lead or visitor. A user can only be merged into another user.
whatsapp_data_cannot_be_mergedThe WhatsApp number on the source contact can't be reassigned to the destination.
telegram_data_cannot_be_mergedThe Telegram sender on the source contact can't be reassigned to the destination.
source_has_telegram_dataThe source contact has Telegram data, which user-into-user merges don't yet support moving.
phone_data_cannot_be_mergedThe phone data on the source contact can't be reassigned to the destination.
Security
bearerAuth
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:"6762f0d51bb69f9f2193bb7f"
intostringrequired

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

Example:"6762f0d51bb69f9f2193bb80"
skip_duplicate_validationboolean

When true, previews the merge even if the contacts don't share a common identifier. Must be a JSON boolean; the string "true" does not bypass the check. Defaults to false.

Default:false
custom_attribute_namesArray of strings

Custom attribute names to include in the previewed attribute changes.

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

Responses

successful

Bodyapplication/json
One of:

Returned when the merge is allowed.

allowedboolean

Always true. The merge is allowed.

Value:true
summaryobject(Merge preview summary)

A summary of the changes the merge would make to the surviving contact.

Response
{
  "allowed": true,
  "summary": {
    "attribute_changes": { … },
    "reassignments": { … }
  }
}