This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
You can also merge a contact with a `role` of `user` into another contact with a `role` of `user`. User-to-user merging is being rolled out gradually: on workspaces where it is not yet available, user-to-user requests return `400` with code `invalid_merge`. User-to-user merges follow stricter rules than lead-to-user merges:
- The two contacts must share an email address or phone number. This requirement can't be bypassed: passing `skip_duplicate_validation` as `true` returns `400` with code `parameter_not_allowed`.
- A source contact (`from`) with WhatsApp data can't be merged into another user yet. Such requests return `422` with code `unprocessable_entity`.
- A user can never be merged into a lead.
Use [Preview a contact merge](/docs/references/preview/rest-api/api.intercom.io/contacts/previewmergecontact) with the same `from` and `into` to check whether a merge would be allowed without performing it.
{% admonition type="warning" name="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.
Expand Down
Expand Up
@@ -8864,6 +8872,34 @@ paths:
message: Contacts can only be merged when they are duplicates
(matching email or phone). Pass skip_duplicate_validation=true
to override this check.
Skip duplicate validation on a user-to-user merge:
value:
type: error.list
errors:
- code: parameter_not_allowed
message: skip_duplicate_validation is not supported for user-to-user
merges; contacts must share an email or phone
schema:
"$ref": "#/components/schemas/error"
'422':
description: Unprocessable Entity
content:
application/json:
examples:
User-to-user contacts are not duplicates:
value:
type: error.list
errors:
- code: unprocessable_entity
message: Contacts can only be merged when they are duplicates
(matching email or phone)
User-to-user source contact has WhatsApp data:
value:
type: error.list
errors:
- code: unprocessable_entity
message: User merge cannot move WhatsApp data yet, so a source
contact with WhatsApp data cannot be merged
schema:
"$ref": "#/components/schemas/error"
'401':
Expand Down
Expand Up
@@ -8911,21 +8947,23 @@ paths:
description: |
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](/docs/references/preview/rest-api/api.intercom.io/contacts/mergecontact).
Send the same `from` and `into` contact IDs you would pass to [Merge contacts](/docs/references/preview/rest-api/api.intercom.io/contacts/mergecontact). For a lead-to-user merge, `from` is a lead and `into` is a user; for a user-to-user merge, both are users.
- 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.
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.
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. This bypass only applies to lead-to-user merges: on a user-to-user preview, passing `skip_duplicate_validation` as `true` returns `400` with code `parameter_not_allowed`.
{% /admonition %}
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. |
| `invalid_merge_role_pair` | The `from`/`into` roles aren't mergeable. A lead can be merged into a user, and a user into another user; a user can never be merged into a lead. |
| `no_shared_identifier` | The contacts share no email, phone, or external ID. Set `skip_duplicate_validation` to preview anyway. |
| `u2u_no_shared_identifier` | User-to-user only: the contacts share no email or phone. `skip_duplicate_validation` can't bypass this for user-to-user merges. |
| `source_has_whatsapp_data` | User-to-user only: the source contact has WhatsApp data, which can't yet be moved by a user-to-user merge. |
| `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. |
Expand Down
Expand Up
@@ -8986,6 +9024,20 @@ paths:
message: These contacts don't share a common identifier (email, phone, or external ID), so they aren't recognised as duplicates. Set skip_duplicate_validation to true to preview the merge anyway.
Skip duplicate validation on a user-to-user preview:
value:
type: error.list
errors:
- code: parameter_not_allowed
message: skip_duplicate_validation is not supported for user-to-user
merges; contacts must share an email or phone
schema:
"$ref": "#/components/schemas/error"
'401':
description: Unauthorized
content:
Expand Down
Expand Up
@@ -37255,7 +37307,7 @@ components:
from:
type: string
description: The unique identifier for the contact to merge away from. Must
be a lead.
be a lead, or a user when performing a user-to-user merge.
example: 5d70dd30de4efd54f42fd526
into:
type: string
Expand All
@@ -37265,7 +37317,9 @@ components:
skip_duplicate_validation:
type: boolean
description: Set to `true` to merge two contacts that are not duplicates
(they share no matching email or phone).
(they share no matching email or phone). Only supported for lead-to-user
merges. A user-to-user merge always requires a shared email or phone,
and passing `true` returns `400` with code `parameter_not_allowed`.
example: true
merge_preview_request:
description: Preview a contact merge.
Expand All
@@ -37277,7 +37331,7 @@ components:
properties:
from:
type: string
description: The unique identifier for the contact to merge away from. Must be a lead.
description: The unique identifier for the contact to merge away from. Must be a lead, or a user when previewing a user-to-user merge.
example: 6762f0d51bb69f9f2193bb7f
into:
type: string
Expand All
@@ -37286,7 +37340,7 @@ components:
skip_duplicate_validation:
type: boolean
default: false
description: When true, previews the merge even if the contacts don't share a common identifier. Defaults to false.
description: When true, previews the merge even if the contacts don't share a common identifier. Defaults to false. Only supported for lead-to-user previews; on a user-to-user preview, passing `true` returns `400` with code `parameter_not_allowed`.
merge_preview_response:
title: Merge preview response
description: The result of a merge preview. Either the merge is allowed (with a summary of the changes) or it is not (with reasons).
Expand Down
Expand Up
@@ -37331,9 +37385,11 @@ components:
enum:
- invalid_merge_role_pair
- no_shared_identifier
- u2u_no_shared_identifier
- facebook_user
- external_lead_channel_not_allowed
- mailing_list
- source_has_whatsapp_data
message:
type: string
description: A human-readable explanation. Display this to people; do not match on it, as the wording may change.
Expand Down
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
[DO NOT MERGE] Document user-to-user contact merges (Preview) #613
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Are you sure you want to change the base?
Uh oh!
There was an error while loading. Please reload this page.
[DO NOT MERGE] Document user-to-user contact merges (Preview) #613
Filter by extension
Viewed files
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
There are no files selected for viewing