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 (a lead) and into (a user) contact IDs you would pass to Merge a lead and a user.

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 lead and would move to the user, and into, how many the user 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-lead 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, phone, or external ID). 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:

code	meaning
`invalid_merge_role_pair`	The `from`/`into` roles aren't mergeable. `from` must be a lead and `into` a user.
`no_shared_identifier`	The contacts share no email, phone, or external ID. Set `skip_duplicate_validation` to preview anyway.
`facebook_user`	Facebook contacts can't be merged.
`external_lead_channel_not_allowed`	The source is an external-channel lead that isn't eligible for merging.
`mailing_list`	Contacts created from a mailing list can't be merged.

Security

bearerAuth

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. Must be a lead.

Example:"6762f0d51bb69f9f2193bb7f"

intostringrequired

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

Example:"6762f0d51bb69f9f2193bb80"

skip_duplicate_validationboolean

When true, previews the merge even if the contacts don't share a common identifier. Defaults to false.

Default:false

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": { … }
  }
}