Document merged contacts behavior in Contacts API

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 (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':
           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 (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
 
         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 (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.
           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.

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 (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':
           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 (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
 
         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 (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.
           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.

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 (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':
           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 (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
 
         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 (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.
           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.

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 (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':
           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 (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
 
         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 (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.
           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.

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 (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':
           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 (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
 
         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 (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.
           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.