From b5c0dc6fe4197f8f9a37ce6ed0353828b15099e3 Mon Sep 17 00:00:00 2001
From: Keith Stenson <147769+kstenson@users.noreply.github.com>
Date: Wed, 15 Apr 2026 18:01:09 +0100
Subject: [PATCH 1/2] Document merged contacts behavior in Contacts API
 endpoints

Clarify that contacts merged via POST /contacts/merge are not retrievable
through the API. The source contact returns 404 on GET, is excluded from
search results, and does not appear in list endpoints. Applied to all
API versions (2.7-2.15 + Preview).

Fixes https://github.com/intercom/intercom/issues/453610

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 descriptions/0/api.intercom.io.yaml    | 27 +++++++++++++++++++++++---
 descriptions/2.10/api.intercom.io.yaml | 27 +++++++++++++++++++++++---
 descriptions/2.11/api.intercom.io.yaml | 27 +++++++++++++++++++++++---
 descriptions/2.12/api.intercom.io.yaml | 27 +++++++++++++++++++++++---
 descriptions/2.13/api.intercom.io.yaml | 27 +++++++++++++++++++++++---
 descriptions/2.14/api.intercom.io.yaml | 27 +++++++++++++++++++++++---
 descriptions/2.15/api.intercom.io.yaml | 27 +++++++++++++++++++++++---
 descriptions/2.7/api.intercom.io.yaml  | 27 +++++++++++++++++++++++---
 descriptions/2.8/api.intercom.io.yaml  | 27 +++++++++++++++++++++++---
 descriptions/2.9/api.intercom.io.yaml  | 27 +++++++++++++++++++++++---
 10 files changed, 240 insertions(+), 30 deletions(-)

diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
index 52e7d9a..cdc24fb 100644
--- a/descriptions/0/api.intercom.io.yaml
+++ b/descriptions/0/api.intercom.io.yaml
@@ -5572,7 +5572,12 @@ paths:
       tags:
       - Contacts
       operationId: ShowContact
-      description: You can fetch the details of a single contact.
+      description: |
+        You can fetch the details of a single contact.
+
+        {% admonition type="warning" name="Merged contacts" %}
+          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -5740,8 +5745,17 @@ paths:
       tags:
       - Contacts
       operationId: MergeContact
-      description: You can merge a contact with a `role` of `lead` into a contact
-        with a `role` of `user`.
+      description: |
+        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
+
+        {% 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.
+          - **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.
+
+          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -5895,6 +5909,10 @@ paths:
           pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
         {% /admonition %}
+        ### Merged Contacts
+
+        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+
         ### Contact Creation Delay
 
         If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
@@ -6045,6 +6063,9 @@ paths:
       operationId: ListContacts
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
+        {% admonition type="info" name="Merged contacts" %}
+          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+        {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml
index cd15438..48591a7 100644
--- a/descriptions/2.10/api.intercom.io.yaml
+++ b/descriptions/2.10/api.intercom.io.yaml
@@ -3322,7 +3322,12 @@ paths:
       tags:
       - Contacts
       operationId: ShowContact
-      description: You can fetch the details of a single contact.
+      description: |
+        You can fetch the details of a single contact.
+
+        {% admonition type="warning" name="Merged contacts" %}
+          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -3488,8 +3493,17 @@ paths:
       tags:
       - Contacts
       operationId: MergeContact
-      description: You can merge a contact with a `role` of `lead` into a contact
-        with a `role` of `user`.
+      description: |
+        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
+
+        {% 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.
+          - **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.
+
+          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -3634,6 +3648,10 @@ paths:
           pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
         {% /admonition %}
+        ### Merged Contacts
+
+        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+
         ### Contact Creation Delay
 
         If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
@@ -3783,6 +3801,9 @@ paths:
       operationId: ListContacts
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
+        {% admonition type="info" name="Merged contacts" %}
+          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+        {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml
index 55c32a1..9726d91 100644
--- a/descriptions/2.11/api.intercom.io.yaml
+++ b/descriptions/2.11/api.intercom.io.yaml
@@ -3401,7 +3401,12 @@ paths:
       tags:
       - Contacts
       operationId: ShowContact
-      description: You can fetch the details of a single contact.
+      description: |
+        You can fetch the details of a single contact.
+
+        {% admonition type="warning" name="Merged contacts" %}
+          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -3567,8 +3572,17 @@ paths:
       tags:
       - Contacts
       operationId: MergeContact
-      description: You can merge a contact with a `role` of `lead` into a contact
-        with a `role` of `user`.
+      description: |
+        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
+
+        {% 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.
+          - **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.
+
+          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -3713,6 +3727,10 @@ paths:
           pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
         {% /admonition %}
+        ### Merged Contacts
+
+        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+
         ### Contact Creation Delay
 
         If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
@@ -3882,6 +3900,9 @@ paths:
       operationId: ListContacts
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
+        {% admonition type="info" name="Merged contacts" %}
+          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+        {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml
index 9cbb4b2..70ca4e6 100644
--- a/descriptions/2.12/api.intercom.io.yaml
+++ b/descriptions/2.12/api.intercom.io.yaml
@@ -3912,7 +3912,12 @@ paths:
       tags:
       - Contacts
       operationId: ShowContact
-      description: You can fetch the details of a single contact.
+      description: |
+        You can fetch the details of a single contact.
+
+        {% admonition type="warning" name="Merged contacts" %}
+          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -4086,8 +4091,17 @@ paths:
       tags:
       - Contacts
       operationId: MergeContact
-      description: You can merge a contact with a `role` of `lead` into a contact
-        with a `role` of `user`.
+      description: |
+        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
+
+        {% 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.
+          - **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.
+
+          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -4240,6 +4254,10 @@ paths:
           pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
         {% /admonition %}
+        ### Merged Contacts
+
+        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+
         ### Contact Creation Delay
 
         If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
@@ -4389,6 +4407,9 @@ paths:
       operationId: ListContacts
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
+        {% admonition type="info" name="Merged contacts" %}
+          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+        {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml
index 4098149..61acbad 100644
--- a/descriptions/2.13/api.intercom.io.yaml
+++ b/descriptions/2.13/api.intercom.io.yaml
@@ -4440,7 +4440,12 @@ paths:
       tags:
       - Contacts
       operationId: ShowContact
-      description: You can fetch the details of a single contact.
+      description: |
+        You can fetch the details of a single contact.
+
+        {% admonition type="warning" name="Merged contacts" %}
+          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -4607,8 +4612,17 @@ paths:
       tags:
       - Contacts
       operationId: MergeContact
-      description: You can merge a contact with a `role` of `lead` into a contact
-        with a `role` of `user`.
+      description: |
+        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
+
+        {% 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.
+          - **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.
+
+          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -4761,6 +4775,10 @@ paths:
           pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
         {% /admonition %}
+        ### Merged Contacts
+
+        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+
         ### Contact Creation Delay
 
         If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
@@ -4910,6 +4928,9 @@ paths:
       operationId: ListContacts
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
+        {% admonition type="info" name="Merged contacts" %}
+          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+        {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml
index 4fcceea..b68c8f4 100644
--- a/descriptions/2.14/api.intercom.io.yaml
+++ b/descriptions/2.14/api.intercom.io.yaml
@@ -4900,7 +4900,12 @@ paths:
       tags:
       - Contacts
       operationId: ShowContact
-      description: You can fetch the details of a single contact.
+      description: |
+        You can fetch the details of a single contact.
+
+        {% admonition type="warning" name="Merged contacts" %}
+          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -5067,8 +5072,17 @@ paths:
       tags:
       - Contacts
       operationId: MergeContact
-      description: You can merge a contact with a `role` of `lead` into a contact
-        with a `role` of `user`.
+      description: |
+        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
+
+        {% 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.
+          - **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.
+
+          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -5221,6 +5235,10 @@ paths:
           pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
         {% /admonition %}
+        ### Merged Contacts
+
+        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+
         ### Contact Creation Delay
 
         If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
@@ -5370,6 +5388,9 @@ paths:
       operationId: ListContacts
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
+        {% admonition type="info" name="Merged contacts" %}
+          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+        {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml
index b49a8ec..eca9a23 100644
--- a/descriptions/2.15/api.intercom.io.yaml
+++ b/descriptions/2.15/api.intercom.io.yaml
@@ -4971,7 +4971,12 @@ paths:
       tags:
       - Contacts
       operationId: ShowContact
-      description: You can fetch the details of a single contact.
+      description: |
+        You can fetch the details of a single contact.
+
+        {% admonition type="warning" name="Merged contacts" %}
+          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -5138,8 +5143,17 @@ paths:
       tags:
       - Contacts
       operationId: MergeContact
-      description: You can merge a contact with a `role` of `lead` into a contact
-        with a `role` of `user`.
+      description: |
+        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
+
+        {% 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.
+          - **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.
+
+          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -5292,6 +5306,10 @@ paths:
           pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
         {% /admonition %}
+        ### Merged Contacts
+
+        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+
         ### Contact Creation Delay
 
         If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
@@ -5441,6 +5459,9 @@ paths:
       operationId: ListContacts
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
+        {% admonition type="info" name="Merged contacts" %}
+          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+        {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml
index de7c263..41343cb 100644
--- a/descriptions/2.7/api.intercom.io.yaml
+++ b/descriptions/2.7/api.intercom.io.yaml
@@ -3541,7 +3541,12 @@ paths:
       tags:
       - Contacts
       operationId: ShowContact
-      description: You can fetch the details of a single contact.
+      description: |
+        You can fetch the details of a single contact.
+
+        {% admonition type="warning" name="Merged contacts" %}
+          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -3706,8 +3711,17 @@ paths:
       tags:
       - Contacts
       operationId: MergeContact
-      description: You can merge a contact with a `role` of `lead` into a contact
-        with a `role` of `user`.
+      description: |
+        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
+
+        {% 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.
+          - **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.
+
+          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -3852,6 +3866,10 @@ paths:
           pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
         {% /admonition %}
+        ### Merged Contacts
+
+        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+
         ### Contact Creation Delay
 
         If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
@@ -4001,6 +4019,9 @@ paths:
       operationId: ListContacts
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
+        {% admonition type="info" name="Merged contacts" %}
+          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+        {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml
index 1ece758..7e5b7a7 100644
--- a/descriptions/2.8/api.intercom.io.yaml
+++ b/descriptions/2.8/api.intercom.io.yaml
@@ -3541,7 +3541,12 @@ paths:
       tags:
       - Contacts
       operationId: ShowContact
-      description: You can fetch the details of a single contact.
+      description: |
+        You can fetch the details of a single contact.
+
+        {% admonition type="warning" name="Merged contacts" %}
+          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -3706,8 +3711,17 @@ paths:
       tags:
       - Contacts
       operationId: MergeContact
-      description: You can merge a contact with a `role` of `lead` into a contact
-        with a `role` of `user`.
+      description: |
+        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
+
+        {% 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.
+          - **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.
+
+          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -3852,6 +3866,10 @@ paths:
           pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
         {% /admonition %}
+        ### Merged Contacts
+
+        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+
         ### Contact Creation Delay
 
         If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
@@ -4001,6 +4019,9 @@ paths:
       operationId: ListContacts
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
+        {% admonition type="info" name="Merged contacts" %}
+          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+        {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml
index 64a41f2..ca92eee 100644
--- a/descriptions/2.9/api.intercom.io.yaml
+++ b/descriptions/2.9/api.intercom.io.yaml
@@ -3541,7 +3541,12 @@ paths:
       tags:
       - Contacts
       operationId: ShowContact
-      description: You can fetch the details of a single contact.
+      description: |
+        You can fetch the details of a single contact.
+
+        {% admonition type="warning" name="Merged contacts" %}
+          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -3706,8 +3711,17 @@ paths:
       tags:
       - Contacts
       operationId: MergeContact
-      description: You can merge a contact with a `role` of `lead` into a contact
-        with a `role` of `user`.
+      description: |
+        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
+
+        {% 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.
+          - **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.
+
+          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
+        {% /admonition %}
       responses:
         '200':
           description: successful
@@ -3852,6 +3866,10 @@ paths:
           pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
         {% /admonition %}
+        ### Merged Contacts
+
+        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+
         ### Contact Creation Delay
 
         If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
@@ -4001,6 +4019,9 @@ paths:
       operationId: ListContacts
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
+        {% admonition type="info" name="Merged contacts" %}
+          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+        {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
           See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.

From ddd5c99b86e9d590f319f49ff58b5c4c132a5bc7 Mon Sep 17 00:00:00 2001
From: Keith Stenson <147769+kstenson@users.noreply.github.com>
Date: Wed, 15 Apr 2026 18:11:39 +0100
Subject: [PATCH 2/2] Fix broken relative links in merged contacts admonitions

Replace /reference/merge-a-lead-and-a-user relative links with plain
text endpoint references (POST /contacts/merge) to stay consistent
with the developer-docs companion PR.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 descriptions/0/api.intercom.io.yaml    | 6 +++---
 descriptions/2.10/api.intercom.io.yaml | 6 +++---
 descriptions/2.11/api.intercom.io.yaml | 6 +++---
 descriptions/2.12/api.intercom.io.yaml | 6 +++---
 descriptions/2.13/api.intercom.io.yaml | 6 +++---
 descriptions/2.14/api.intercom.io.yaml | 6 +++---
 descriptions/2.15/api.intercom.io.yaml | 6 +++---
 descriptions/2.7/api.intercom.io.yaml  | 6 +++---
 descriptions/2.8/api.intercom.io.yaml  | 6 +++---
 descriptions/2.9/api.intercom.io.yaml  | 6 +++---
 10 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
index cdc24fb..d333fa9 100644
--- a/descriptions/0/api.intercom.io.yaml
+++ b/descriptions/0/api.intercom.io.yaml
@@ -5576,7 +5576,7 @@ paths:
         You can fetch the details of a single contact.
 
         {% admonition type="warning" name="Merged contacts" %}
-          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+          If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
         {% /admonition %}
       responses:
         '200':
@@ -5911,7 +5911,7 @@ paths:
         {% /admonition %}
         ### Merged Contacts
 
-        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
 
         ### Contact Creation Delay
 
@@ -6064,7 +6064,7 @@ paths:
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
         {% admonition type="info" name="Merged contacts" %}
-          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
         {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml
index 48591a7..ee6ed41 100644
--- a/descriptions/2.10/api.intercom.io.yaml
+++ b/descriptions/2.10/api.intercom.io.yaml
@@ -3326,7 +3326,7 @@ paths:
         You can fetch the details of a single contact.
 
         {% admonition type="warning" name="Merged contacts" %}
-          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+          If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
         {% /admonition %}
       responses:
         '200':
@@ -3650,7 +3650,7 @@ paths:
         {% /admonition %}
         ### Merged Contacts
 
-        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
 
         ### Contact Creation Delay
 
@@ -3802,7 +3802,7 @@ paths:
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
         {% admonition type="info" name="Merged contacts" %}
-          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
         {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml
index 9726d91..ec00de0 100644
--- a/descriptions/2.11/api.intercom.io.yaml
+++ b/descriptions/2.11/api.intercom.io.yaml
@@ -3405,7 +3405,7 @@ paths:
         You can fetch the details of a single contact.
 
         {% admonition type="warning" name="Merged contacts" %}
-          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+          If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
         {% /admonition %}
       responses:
         '200':
@@ -3729,7 +3729,7 @@ paths:
         {% /admonition %}
         ### Merged Contacts
 
-        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
 
         ### Contact Creation Delay
 
@@ -3901,7 +3901,7 @@ paths:
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
         {% admonition type="info" name="Merged contacts" %}
-          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
         {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml
index 70ca4e6..a80e2ad 100644
--- a/descriptions/2.12/api.intercom.io.yaml
+++ b/descriptions/2.12/api.intercom.io.yaml
@@ -3916,7 +3916,7 @@ paths:
         You can fetch the details of a single contact.
 
         {% admonition type="warning" name="Merged contacts" %}
-          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+          If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
         {% /admonition %}
       responses:
         '200':
@@ -4256,7 +4256,7 @@ paths:
         {% /admonition %}
         ### Merged Contacts
 
-        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
 
         ### Contact Creation Delay
 
@@ -4408,7 +4408,7 @@ paths:
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
         {% admonition type="info" name="Merged contacts" %}
-          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
         {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml
index 61acbad..62d2187 100644
--- a/descriptions/2.13/api.intercom.io.yaml
+++ b/descriptions/2.13/api.intercom.io.yaml
@@ -4444,7 +4444,7 @@ paths:
         You can fetch the details of a single contact.
 
         {% admonition type="warning" name="Merged contacts" %}
-          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+          If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
         {% /admonition %}
       responses:
         '200':
@@ -4777,7 +4777,7 @@ paths:
         {% /admonition %}
         ### Merged Contacts
 
-        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
 
         ### Contact Creation Delay
 
@@ -4929,7 +4929,7 @@ paths:
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
         {% admonition type="info" name="Merged contacts" %}
-          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
         {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml
index b68c8f4..8847140 100644
--- a/descriptions/2.14/api.intercom.io.yaml
+++ b/descriptions/2.14/api.intercom.io.yaml
@@ -4904,7 +4904,7 @@ paths:
         You can fetch the details of a single contact.
 
         {% admonition type="warning" name="Merged contacts" %}
-          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+          If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
         {% /admonition %}
       responses:
         '200':
@@ -5237,7 +5237,7 @@ paths:
         {% /admonition %}
         ### Merged Contacts
 
-        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
 
         ### Contact Creation Delay
 
@@ -5389,7 +5389,7 @@ paths:
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
         {% admonition type="info" name="Merged contacts" %}
-          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
         {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml
index eca9a23..39e6b72 100644
--- a/descriptions/2.15/api.intercom.io.yaml
+++ b/descriptions/2.15/api.intercom.io.yaml
@@ -4975,7 +4975,7 @@ paths:
         You can fetch the details of a single contact.
 
         {% admonition type="warning" name="Merged contacts" %}
-          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+          If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
         {% /admonition %}
       responses:
         '200':
@@ -5308,7 +5308,7 @@ paths:
         {% /admonition %}
         ### Merged Contacts
 
-        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
 
         ### Contact Creation Delay
 
@@ -5460,7 +5460,7 @@ paths:
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
         {% admonition type="info" name="Merged contacts" %}
-          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
         {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml
index 41343cb..8c75b03 100644
--- a/descriptions/2.7/api.intercom.io.yaml
+++ b/descriptions/2.7/api.intercom.io.yaml
@@ -3545,7 +3545,7 @@ paths:
         You can fetch the details of a single contact.
 
         {% admonition type="warning" name="Merged contacts" %}
-          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+          If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
         {% /admonition %}
       responses:
         '200':
@@ -3868,7 +3868,7 @@ paths:
         {% /admonition %}
         ### Merged Contacts
 
-        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
 
         ### Contact Creation Delay
 
@@ -4020,7 +4020,7 @@ paths:
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
         {% admonition type="info" name="Merged contacts" %}
-          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
         {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml
index 7e5b7a7..6d937bd 100644
--- a/descriptions/2.8/api.intercom.io.yaml
+++ b/descriptions/2.8/api.intercom.io.yaml
@@ -3545,7 +3545,7 @@ paths:
         You can fetch the details of a single contact.
 
         {% admonition type="warning" name="Merged contacts" %}
-          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+          If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
         {% /admonition %}
       responses:
         '200':
@@ -3868,7 +3868,7 @@ paths:
         {% /admonition %}
         ### Merged Contacts
 
-        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
 
         ### Contact Creation Delay
 
@@ -4020,7 +4020,7 @@ paths:
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
         {% admonition type="info" name="Merged contacts" %}
-          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
         {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.
diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml
index ca92eee..8fbac9b 100644
--- a/descriptions/2.9/api.intercom.io.yaml
+++ b/descriptions/2.9/api.intercom.io.yaml
@@ -3545,7 +3545,7 @@ paths:
         You can fetch the details of a single contact.
 
         {% admonition type="warning" name="Merged contacts" %}
-          If a contact has been merged into another contact via the [Merge endpoint](/reference/merge-a-lead-and-a-user), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
+          If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return a `404 Not Found` error. Use the merged-into contact's ID instead.
         {% /admonition %}
       responses:
         '200':
@@ -3868,7 +3868,7 @@ paths:
         {% /admonition %}
         ### Merged Contacts
 
-        Contacts that have been [merged](/reference/merge-a-lead-and-a-user) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
+        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.
 
         ### Contact Creation Delay
 
@@ -4020,7 +4020,7 @@ paths:
       description: |
         You can fetch a list of all contacts (ie. users or leads) in your workspace.
         {% admonition type="info" name="Merged contacts" %}
-          Contacts that have been [merged](/reference/merge-a-lead-and-a-user) will not appear in list results. Only the target contact from the merge remains accessible.
+          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
         {% /admonition %}
         {% admonition type="warning" name="Pagination" %}
           You can use pagination to limit the number of results returned. The default is `50` results per page.