You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Document merged contacts behavior in Contacts API (#454)
* 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).
Fixesintercom/intercom#453610
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* 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>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
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.
5580
+
{% /admonition %}
5576
5581
responses:
5577
5582
'200':
5578
5583
description: successful
@@ -5740,8 +5745,17 @@ paths:
5740
5745
tags:
5741
5746
- Contacts
5742
5747
operationId: MergeContact
5743
-
description: You can merge a contact with a `role` of `lead` into a contact
5744
-
with a `role` of `user`.
5748
+
description: |
5749
+
You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
5750
+
5751
+
{% admonition type="warning" name="Merged contacts are not retrievable via the API" %}
5752
+
Once a merge is completed, the source contact (`from`) is permanently removed from the active contact list. This means:
5753
+
- **GET /contacts/{id}** — Requesting the source contact by its original ID will return a `404 Not Found` error.
5754
+
- **POST /contacts/search** — The source contact will not appear in search results, including queries filtered by `updated_at`.
5755
+
- **GET /contacts** — The source contact will not appear in list results.
5756
+
5757
+
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.
5758
+
{% /admonition %}
5745
5759
responses:
5746
5760
'200':
5747
5761
description: successful
@@ -5895,6 +5909,10 @@ paths:
5895
5909
pagination to limit the number of results returned. The default is `50` results per page.
5896
5910
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.
5897
5911
{% /admonition %}
5912
+
### Merged Contacts
5913
+
5914
+
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.
5915
+
5898
5916
### Contact Creation Delay
5899
5917
5900
5918
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:
6045
6063
operationId: ListContacts
6046
6064
description: |
6047
6065
You can fetch a list of all contacts (ie. users or leads) in your workspace.
Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
6068
+
{% /admonition %}
6048
6069
{% admonition type="warning" name="Pagination" %}
6049
6070
You can use pagination to limit the number of results returned. The default is `50` results per page.
6050
6071
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.
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.
3330
+
{% /admonition %}
3326
3331
responses:
3327
3332
'200':
3328
3333
description: successful
@@ -3488,8 +3493,17 @@ paths:
3488
3493
tags:
3489
3494
- Contacts
3490
3495
operationId: MergeContact
3491
-
description: You can merge a contact with a `role` of `lead` into a contact
3492
-
with a `role` of `user`.
3496
+
description: |
3497
+
You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
3498
+
3499
+
{% admonition type="warning" name="Merged contacts are not retrievable via the API" %}
3500
+
Once a merge is completed, the source contact (`from`) is permanently removed from the active contact list. This means:
3501
+
- **GET /contacts/{id}** — Requesting the source contact by its original ID will return a `404 Not Found` error.
3502
+
- **POST /contacts/search** — The source contact will not appear in search results, including queries filtered by `updated_at`.
3503
+
- **GET /contacts** — The source contact will not appear in list results.
3504
+
3505
+
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.
3506
+
{% /admonition %}
3493
3507
responses:
3494
3508
'200':
3495
3509
description: successful
@@ -3634,6 +3648,10 @@ paths:
3634
3648
pagination to limit the number of results returned. The default is `50` results per page.
3635
3649
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.
3636
3650
{% /admonition %}
3651
+
### Merged Contacts
3652
+
3653
+
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.
3654
+
3637
3655
### Contact Creation Delay
3638
3656
3639
3657
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:
3783
3801
operationId: ListContacts
3784
3802
description: |
3785
3803
You can fetch a list of all contacts (ie. users or leads) in your workspace.
Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
3806
+
{% /admonition %}
3786
3807
{% admonition type="warning" name="Pagination" %}
3787
3808
You can use pagination to limit the number of results returned. The default is `50` results per page.
3788
3809
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.
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.
3409
+
{% /admonition %}
3405
3410
responses:
3406
3411
'200':
3407
3412
description: successful
@@ -3567,8 +3572,17 @@ paths:
3567
3572
tags:
3568
3573
- Contacts
3569
3574
operationId: MergeContact
3570
-
description: You can merge a contact with a `role` of `lead` into a contact
3571
-
with a `role` of `user`.
3575
+
description: |
3576
+
You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
3577
+
3578
+
{% admonition type="warning" name="Merged contacts are not retrievable via the API" %}
3579
+
Once a merge is completed, the source contact (`from`) is permanently removed from the active contact list. This means:
3580
+
- **GET /contacts/{id}** — Requesting the source contact by its original ID will return a `404 Not Found` error.
3581
+
- **POST /contacts/search** — The source contact will not appear in search results, including queries filtered by `updated_at`.
3582
+
- **GET /contacts** — The source contact will not appear in list results.
3583
+
3584
+
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.
3585
+
{% /admonition %}
3572
3586
responses:
3573
3587
'200':
3574
3588
description: successful
@@ -3713,6 +3727,10 @@ paths:
3713
3727
pagination to limit the number of results returned. The default is `50` results per page.
3714
3728
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.
3715
3729
{% /admonition %}
3730
+
### Merged Contacts
3731
+
3732
+
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.
3733
+
3716
3734
### Contact Creation Delay
3717
3735
3718
3736
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:
3882
3900
operationId: ListContacts
3883
3901
description: |
3884
3902
You can fetch a list of all contacts (ie. users or leads) in your workspace.
Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
3905
+
{% /admonition %}
3885
3906
{% admonition type="warning" name="Pagination" %}
3886
3907
You can use pagination to limit the number of results returned. The default is `50` results per page.
3887
3908
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.
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.
3920
+
{% /admonition %}
3916
3921
responses:
3917
3922
'200':
3918
3923
description: successful
@@ -4086,8 +4091,17 @@ paths:
4086
4091
tags:
4087
4092
- Contacts
4088
4093
operationId: MergeContact
4089
-
description: You can merge a contact with a `role` of `lead` into a contact
4090
-
with a `role` of `user`.
4094
+
description: |
4095
+
You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
4096
+
4097
+
{% admonition type="warning" name="Merged contacts are not retrievable via the API" %}
4098
+
Once a merge is completed, the source contact (`from`) is permanently removed from the active contact list. This means:
4099
+
- **GET /contacts/{id}** — Requesting the source contact by its original ID will return a `404 Not Found` error.
4100
+
- **POST /contacts/search** — The source contact will not appear in search results, including queries filtered by `updated_at`.
4101
+
- **GET /contacts** — The source contact will not appear in list results.
4102
+
4103
+
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.
4104
+
{% /admonition %}
4091
4105
responses:
4092
4106
'200':
4093
4107
description: successful
@@ -4240,6 +4254,10 @@ paths:
4240
4254
pagination to limit the number of results returned. The default is `50` results per page.
4241
4255
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.
4242
4256
{% /admonition %}
4257
+
### Merged Contacts
4258
+
4259
+
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.
4260
+
4243
4261
### Contact Creation Delay
4244
4262
4245
4263
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:
4389
4407
operationId: ListContacts
4390
4408
description: |
4391
4409
You can fetch a list of all contacts (ie. users or leads) in your workspace.
Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
4412
+
{% /admonition %}
4392
4413
{% admonition type="warning" name="Pagination" %}
4393
4414
You can use pagination to limit the number of results returned. The default is `50` results per page.
4394
4415
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.
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.
4448
+
{% /admonition %}
4444
4449
responses:
4445
4450
'200':
4446
4451
description: successful
@@ -4607,8 +4612,17 @@ paths:
4607
4612
tags:
4608
4613
- Contacts
4609
4614
operationId: MergeContact
4610
-
description: You can merge a contact with a `role` of `lead` into a contact
4611
-
with a `role` of `user`.
4615
+
description: |
4616
+
You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.
4617
+
4618
+
{% admonition type="warning" name="Merged contacts are not retrievable via the API" %}
4619
+
Once a merge is completed, the source contact (`from`) is permanently removed from the active contact list. This means:
4620
+
- **GET /contacts/{id}** — Requesting the source contact by its original ID will return a `404 Not Found` error.
4621
+
- **POST /contacts/search** — The source contact will not appear in search results, including queries filtered by `updated_at`.
4622
+
- **GET /contacts** — The source contact will not appear in list results.
4623
+
4624
+
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.
4625
+
{% /admonition %}
4612
4626
responses:
4613
4627
'200':
4614
4628
description: successful
@@ -4761,6 +4775,10 @@ paths:
4761
4775
pagination to limit the number of results returned. The default is `50` results per page.
4762
4776
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.
4763
4777
{% /admonition %}
4778
+
### Merged Contacts
4779
+
4780
+
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.
4781
+
4764
4782
### Contact Creation Delay
4765
4783
4766
4784
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:
4910
4928
operationId: ListContacts
4911
4929
description: |
4912
4930
You can fetch a list of all contacts (ie. users or leads) in your workspace.
Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
4933
+
{% /admonition %}
4913
4934
{% admonition type="warning" name="Pagination" %}
4914
4935
You can use pagination to limit the number of results returned. The default is `50` results per page.
4915
4936
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.
0 commit comments