From bf42d3b04d8c29fd5a50d876bc0346b0fae275ab Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 27 May 2026 15:17:05 +0100 Subject: [PATCH 1/3] Add contact merge history endpoints and 410 Gone for merged contacts - Add merge_history field (opt-in via include_merge_history param) to contact responses - Add GET /contacts/{contact_id}/merge_history paginated endpoint (max 150 per page) - Add include_merge_history query param to 6 contact endpoints - Add merge_history_item and merge_history_list schemas - Merged contacts now return 410 Gone with Link header instead of 404 Co-Authored-By: Claude Sonnet 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 204 +++++++++++++++++++++++++++- 1 file changed, 203 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index ab24773..05f2409 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -481,6 +481,7 @@ paths: - temporary_expectation_change - upfront_email_collection_change - welcome_message_change + - hide_csat_from_agents_setting_change schema: "$ref": "#/components/schemas/activity_log_event_type_list" '401': @@ -5481,6 +5482,14 @@ paths: required: true schema: type: string + - name: include_merge_history + in: query + description: Pass `true` to include the contact's merge history in the response. + Only returned for contacts with a `user` role. + required: false + schema: + type: boolean + default: false tags: - Contacts - Custom Object Instances @@ -5744,6 +5753,14 @@ paths: required: true schema: type: string + - name: include_merge_history + in: query + description: Pass `true` to include the contact's merge history in the response. + Only returned for contacts with a `user` role. + required: false + schema: + type: boolean + default: false tags: - Contacts operationId: ShowContact @@ -5954,6 +5971,14 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: include_merge_history + in: query + description: Pass `true` to include the merge history of the resulting contact + in the response. Only returned for contacts with a `user` role. + required: false + schema: + type: boolean + default: false tags: - Contacts operationId: MergeContact @@ -5962,7 +5987,7 @@ paths: {% 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 a `404 Not Found` error. + - **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. - **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. @@ -6105,6 +6130,14 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: include_merge_history + in: query + description: Pass `true` to include a `merge_history` array on each contact + in the response. Only returned for contacts with a `user` role. + required: false + schema: + type: boolean + default: false tags: - Contacts operationId: SearchContacts @@ -6270,6 +6303,14 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" + - name: include_merge_history + in: query + description: Pass `true` to include a `merge_history` array on each contact + in the response. Only returned for contacts with a `user` role. + required: false + schema: + type: boolean + default: false tags: - Contacts operationId: ListContacts @@ -6469,6 +6510,14 @@ paths: description: The external ID of the user that you want to retrieve schema: type: string + - name: include_merge_history + in: query + description: Pass `true` to include the contact's merge history in the response. + Only returned for contacts with a `user` role. + required: false + schema: + type: boolean + default: false tags: - Contacts operationId: ShowContactByExternalId @@ -6696,6 +6745,98 @@ paths: application/json: schema: "$ref": "#/components/schemas/contact_blocked" + "/contacts/{contact_id}/merge_history": + get: + summary: Get contact merge history + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: contact_id + in: path + description: The id of the contact to fetch merge history for. + example: 63a07ddf05a32042dffac965 + required: true + schema: + type: string + - name: cursor + in: query + description: A cursor for pagination. Pass the `next_cursor` value from a + previous response to fetch the next page. + required: false + schema: + type: string + - name: per_page + in: query + description: The number of results to return per page (default 50, max 150). + required: false + schema: + type: integer + default: 50 + maximum: 150 + - name: order + in: query + description: The order to return results in. Defaults to descending. + required: false + schema: + type: string + enum: + - asc + - desc + tags: + - Contacts + operationId: ListContactMergeHistory + description: | + Retrieve the paginated list of contacts that have been merged into a given contact. + + Only available for contacts with a `user` role. Returns a `404` if the contact is not found or has a `lead` role. + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: list + data: + - type: merge_history + source_contact_id: 5ba682d23d7cf92bef87bfd3 + source_contact_role: lead + merged_at: 1571672154 + next_cursor: + has_more: false + schema: + "$ref": "#/components/schemas/merge_history_list" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 45b30bd1-75d2-40cc-bb39-74ac133a2836 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '404': + description: Contact not found + content: + application/json: + examples: + Contact not found: + value: + type: error.list + request_id: 45b30bd1-75d2-40cc-bb39-74ac133a2836 + errors: + - code: not_found + message: Contact not found + schema: + "$ref": "#/components/schemas/error" "/contacts/bulk": post: summary: Bulk update contacts @@ -20178,6 +20319,7 @@ components: - temporary_expectation_change - upfront_email_collection_change - welcome_message_change + - hide_csat_from_agents_setting_change example: app_name_change activity_description: type: string @@ -22493,6 +22635,66 @@ components: "$ref": "#/components/schemas/contact_location" social_profiles: "$ref": "#/components/schemas/contact_social_profiles" + merge_history: + type: array + nullable: true + description: 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. + items: + "$ref": "#/components/schemas/merge_history_item" + merge_history_item: + title: Merge History Item + type: object + description: A record of a contact that was merged into another contact. + properties: + type: + type: string + description: The type of object. + example: merge_history + source_contact_id: + type: string + description: The Intercom ID of the contact that was merged into this contact. + example: 5ba682d23d7cf92bef87bfd3 + source_contact_role: + type: string + description: The role of the contact that was merged in. + enum: + - lead + - user + example: lead + merged_at: + type: integer + nullable: true + format: date-time + description: "(UNIX timestamp) The time when the merge occurred." + example: 1571672154 + merge_history_list: + title: Merge History List + type: object + description: A paginated list of merge history entries for a contact. + properties: + type: + type: string + description: The type of object. + enum: + - list + example: list + data: + type: array + description: An array of merge history entries. + items: + "$ref": "#/components/schemas/merge_history_item" + next_cursor: + type: string + nullable: true + description: A cursor to pass as the `cursor` query parameter to fetch + the next page of results. Absent when there are no more pages. + example: WyIxNjM0NTY3ODkwIl0 + has_more: + type: boolean + description: Whether there are more results to fetch. + example: false contact_attached_companies: title: Contact Attached Companies type: object From 18cf5b6dec427cc64ffb02d7cef46ed73b0aa854 Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 27 May 2026 16:31:04 +0100 Subject: [PATCH 2/3] Add minimum: 1 to per_page on merge_history endpoint Co-Authored-By: Claude Sonnet 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 05f2409..ca4707b 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -6774,6 +6774,7 @@ paths: schema: type: integer default: 50 + minimum: 1 maximum: 150 - name: order in: query From 34ff4b4b8178a91fc937d7657df0e72bc546a482 Mon Sep 17 00:00:00 2001 From: dq Date: Thu, 28 May 2026 09:30:41 +0100 Subject: [PATCH 3/3] Address PR review: path param and next_cursor example - Rename path /contacts/{contact_id}/merge_history to /contacts/{id}/merge_history - Add next_cursor example value to response example Co-Authored-By: Claude Sonnet 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index ca4707b..2327b2a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -6745,7 +6745,7 @@ paths: application/json: schema: "$ref": "#/components/schemas/contact_blocked" - "/contacts/{contact_id}/merge_history": + "/contacts/{id}/merge_history": get: summary: Get contact merge history parameters: @@ -6753,7 +6753,7 @@ paths: in: header schema: "$ref": "#/components/schemas/intercom_version" - - name: contact_id + - name: id in: path description: The id of the contact to fetch merge history for. example: 63a07ddf05a32042dffac965 @@ -6806,8 +6806,8 @@ paths: source_contact_id: 5ba682d23d7cf92bef87bfd3 source_contact_role: lead merged_at: 1571672154 - next_cursor: - has_more: false + next_cursor: eyJpZCI6IjYyMzQ1NiJ9 + has_more: true schema: "$ref": "#/components/schemas/merge_history_list" '401':