diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
index be7b0b4c..f16ac455 100644
--- a/descriptions/0/api.intercom.io.yaml
+++ b/descriptions/0/api.intercom.io.yaml
@@ -7010,13 +7010,17 @@ paths:
in: path
required: true
description: The unique identifier for the contact which is given by Intercom
+ example: 58a430d35458202d41b1e65b
schema:
type: string
tags:
- Companies
- Contacts
operationId: attachContactToACompany
- description: You can attach a company to a single contact.
+ description: |
+ You can attach a company to a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -7042,14 +7046,14 @@ paths:
segments:
type: segment.list
segments: []
+ plan: {}
+ custom_attributes: {}
notes:
type: note.list
data: []
url: "/companies/6762f09a1bb69f9f2193bb34/notes"
total_count: 0
has_more: false
- plan: {}
- custom_attributes: {}
schema:
"$ref": "#/components/schemas/company"
'400':
@@ -7074,7 +7078,7 @@ paths:
schema:
"$ref": "#/components/schemas/error"
'404':
- description: Company Not Found
+ description: Company Not Found or Contact Not Found
content:
application/json:
examples:
@@ -7085,6 +7089,13 @@ paths:
errors:
- code: company_not_found
message: Company Not Found
+ Contact Not Found:
+ value:
+ type: error.list
+ request_id: 7b1f5e2c-19c8-4c7f-9f0a-6f0a6a0ad3c1
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
'401':
@@ -7099,6 +7110,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 1daf6d3f-99ba-59c7-86f7-5d966270f7d3
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -7140,6 +7158,36 @@ paths:
in: header
schema:
"$ref": "#/components/schemas/intercom_version"
+ - name: page
+ in: query
+ required: false
+ description: The page of results to fetch. Values below 1 are treated as 1.
+ schema:
+ type: integer
+ default: 1
+ example: 1
+ - name: per_page
+ in: query
+ required: false
+ description: The number of companies to return per page. The maximum is 60; a value above
+ 60 returns a `400` error with code `parameter_invalid`.
+ schema:
+ type: integer
+ default: 50
+ maximum: 60
+ example: 50
+ - name: order
+ in: query
+ required: false
+ description: The order of the companies by when they were last active (`last_request_at`).
+ The value is case-insensitive, and any value other than `asc` is treated as `desc`.
+ schema:
+ type: string
+ enum:
+ - asc
+ - desc
+ default: desc
+ example: desc
tags:
- Contacts
- Companies
@@ -7175,6 +7223,12 @@ paths:
segments: []
plan: {}
custom_attributes: {}
+ notes:
+ type: note.list
+ data: []
+ url: "/companies/6762f0a61bb69f9f2193bb55/notes"
+ total_count: 0
+ has_more: false
pages:
type: pages
next:
@@ -7184,6 +7238,20 @@ paths:
total_count: 1
schema:
"$ref": "#/components/schemas/contact_attached_companies"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Per page too big:
+ value:
+ type: error.list
+ request_id: 3f1c2b9e-6a4d-4c8e-9b7a-2d5e8f0a1c34
+ errors:
+ - code: parameter_invalid
+ message: Per Page is too big
+ schema:
+ "$ref": "#/components/schemas/error"
'404':
description: Contact not found
content:
@@ -7238,7 +7306,10 @@ paths:
- Companies
- Contacts
operationId: detachContactFromACompany
- description: You can detach a company from a single contact.
+ description: |
+ You can detach a company from a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -7266,10 +7337,16 @@ paths:
segments: []
plan: {}
custom_attributes: {}
+ notes:
+ type: note.list
+ data: []
+ url: "/companies/6762f0a01bb69f9f2193bb44/notes"
+ total_count: 0
+ has_more: false
schema:
"$ref": "#/components/schemas/company"
'404':
- description: Contact Not Found
+ description: Company Not Found or Contact Not Found
content:
application/json:
examples:
@@ -7301,6 +7378,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 11900fce-9e5c-5d21-84d5-5bcf188287fd
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts/{contact_id}/granted_companies":
@@ -8383,7 +8467,10 @@ paths:
- Contacts
- Segments
operationId: listSegmentsForAContact
- description: You can fetch a list of segments that are associated to a contact.
+ description: |
+ You can fetch a list of segments that are associated to a contact.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -8428,6 +8515,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: ca383411-d6ac-5db4-9c4d-352b36f69c8d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts/{contact_id}/subscriptions":
@@ -8553,6 +8647,8 @@ paths:
2.Attaching a contact to an opt-in subscription type will opt that user in to receiving messages related to that subscription type.
This will return a subscription type model for the subscription type that was added to the contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -8610,6 +8706,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 82051728-b8a8-5bfd-9f10-71f9a1dc3107
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -8619,7 +8722,6 @@ paths:
type: object
required:
- id
- - consent_type
properties:
id:
type: string
@@ -8628,7 +8730,8 @@ paths:
example: '37846'
consent_type:
type: string
- description: The consent_type of a subscription, opt_out or opt_in.
+ description: Ignored. Whether the contact is opted in or out is decided
+ by the subscription type's own `consent_type`, not by this value.
example: opt_in
examples:
successful:
@@ -8673,9 +8776,12 @@ paths:
schema:
type: string
operationId: detachSubscriptionTypeToContact
- description: You can remove a specific subscription from a contact. This will
+ description: |
+ You can remove a specific subscription from a contact. This will
return a subscription type model for the subscription type that was removed
from the contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -8733,6 +8839,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 9c562afa-93d0-53d2-bfa4-bb6463fa84ee
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts/{contact_id}/tags":
@@ -8821,8 +8934,11 @@ paths:
schema:
type: string
operationId: attachTagToContact
- description: You can tag a specific contact. This will return a tag object for
+ description: |
+ You can tag a specific contact. This will return a tag object for
the tag that was added to the contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -8873,6 +8989,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 42e197b1-6bc2-5504-915d-97e9e59f6c28
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -8892,11 +9015,11 @@ paths:
successful:
summary: successful
value:
- id: 81
+ id: '81'
contact_not_found:
summary: Contact not found
value:
- id: 82
+ id: '82'
tag_not_found:
summary: Tag not found
value:
@@ -8927,8 +9050,11 @@ paths:
schema:
type: string
operationId: detachTagFromContact
- description: You can remove tag from a specific contact. This will return a
+ description: |
+ You can remove tag from a specific contact. This will return a
tag object for the tag that was removed from the contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -8979,6 +9105,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: c6d0888c-4330-545c-8476-656828fed13d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts/deleted":
@@ -8992,7 +9125,9 @@ paths:
- name: per_page
in: query
description: The number of results per page. Defaults to `10`, with a maximum
- of `150`.
+ of `150`; larger values are treated as `150`. Only the leading digits are read,
+ so `1.5` is treated as `1`. A value that doesn't start with a positive integer,
+ such as `0` or `abc`, returns a `400` error with code `invalid_per_page`.
required: false
schema:
type: integer
@@ -9007,6 +9142,14 @@ paths:
type: integer
minimum: 1
default: 1
+ - name: escape_identity
+ in: query
+ description: By default, `email` values in the response are HTML-escaped (for example,
+ `&` is returned as `&`). Pass `false` to return them unescaped.
+ required: false
+ schema:
+ type: boolean
+ default: true
tags:
- Contacts
operationId: listDeletedContacts
@@ -9017,6 +9160,8 @@ paths:
is inactive: `archived`, `blocked`, `merged`, `pending_deletion`, or `permanently_deleted`.
`merged_into_id` is present only when `status` is `merged`, and `external_id` and `email`
are `null` for `permanently_deleted` contacts.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -9069,6 +9214,13 @@ paths:
errors:
- code: invalid_page
message: page must be a positive integer
+ Invalid per_page:
+ value:
+ type: error.list
+ request_id: 7b2c3d4e-5f6a-4b8c-9d0e-1f2a3b4c5d6e
+ errors:
+ - code: invalid_per_page
+ message: per_page must be a positive integer
schema:
"$ref": "#/components/schemas/error"
'401':
@@ -9083,6 +9235,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 4cd97183-4b6b-5eb9-a020-439cc6964338
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts/{id}":
@@ -9103,7 +9262,7 @@ paths:
- name: include_merge_history
in: query
description: Pass `true` to include the contact's merge history in the response.
- Only returned for contacts with a `user` role.
+ Returned for contacts of any role, with at most the 10 most recent merges.
required: false
schema:
type: boolean
@@ -9120,6 +9279,8 @@ paths:
See _`update a contact with an association to a custom object instance`_ in the request/response examples to see the custom object association format.
{% /admonition %}
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -9134,6 +9295,7 @@ paths:
external_id: '70'
role: user
email: joebloggs@intercom.io
+ email_domain: intercom.io
email_verified: false
phone:
formatted_phone:
@@ -9216,6 +9378,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
update a contact with an association to a custom object instance:
value:
@@ -9225,6 +9389,7 @@ paths:
external_id: '70'
role: user
email: joebloggs@intercom.io
+ email_domain: intercom.io
email_verified: false
phone:
formatted_phone:
@@ -9318,6 +9483,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
allOf:
@@ -9340,6 +9507,84 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 186669b6-de99-567c-91ac-c5d9e513b0a6
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Invalid timestamp:
+ value:
+ type: error.list
+ request_id: 2d0c4b6e-8f1a-4c3d-9e5b-7a6f8d9c0b1e
+ errors:
+ - code: parameter_invalid
+ message: "'signed_up_at' appears to be in milliseconds. Timestamps
+ must be Unix timestamps in seconds."
+ Owner not a teammate:
+ value:
+ type: error.list
+ request_id: 3e1d5c7f-9a2b-4d4e-8f6c-8b7a9e0d1c2f
+ errors:
+ - code: parameter_invalid
+ message: The owner specified is not a member of the app
+ Custom attribute does not exist:
+ value:
+ type: error.list
+ request_id: 4f2e6d8a-0b3c-4e5f-9a7d-9c8b0f1e2d3a
+ errors:
+ - code: parameter_invalid
+ message: Custom attribute 'plan_tier' does not exist
+ Invalid custom attributes:
+ value:
+ type: error.list
+ request_id: 5a3f7e9b-1c4d-4f6a-8b8e-0d9c1a2f3e4b
+ errors:
+ - code: nested_custom_attributes
+ message: "'custom_attributes' must be an object"
+ User can't become a lead:
+ value:
+ type: error.list
+ request_id: 8e4c2a6f-3b7d-4e9a-a1c5-6f0d2b8e4a37
+ errors:
+ - code: client_error
+ message: Contact with user role can't be converted to a lead
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 6b4a8f0c-2d5e-4a7b-9c9f-1e0d2b3a4f5c
+ errors:
+ - code: not_found
+ message: User Not Found
+ schema:
+ "$ref": "#/components/schemas/error"
+ '422':
+ description: Unprocessable Entity
+ content:
+ application/json:
+ examples:
+ Invalid email:
+ value:
+ type: error.list
+ request_id: 7c5b9a1d-3e6f-4b8c-8d0a-2f1e3c4b5a6d
+ errors:
+ - code: parameter_invalid
+ message: "'email' is not a valid email address."
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -9378,11 +9623,21 @@ paths:
- name: include_merge_history
in: query
description: Pass `true` to include the contact's merge history in the response.
- Only returned for contacts with a `user` role.
+ Returned for contacts of any role, with at most the 10 most recent merges.
required: false
schema:
type: boolean
default: false
+ - name: escape_identity
+ in: query
+ description: By default, `name` and `email` values in the response, including nested
+ ones such as social profile names, are HTML-escaped (for example, `&` is returned
+ as `&`). Custom attributes and tags are never escaped. Pass `false` to return
+ them unescaped.
+ required: false
+ schema:
+ type: boolean
+ default: true
tags:
- Contacts
operationId: ShowContact
@@ -9407,6 +9662,8 @@ paths:
The `Link` header contains the path to the final merge target, resolving multi-hop merge chains (up to 3 hops).
{% /admonition %}
+
+ Requires the `read_single_user`, `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -9421,6 +9678,7 @@ paths:
external_id: '70'
role: user
email: joe@bloggs.com
+ email_domain: bloggs.com
email_verified: false
phone:
formatted_phone:
@@ -9503,6 +9761,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
allOf:
@@ -9525,6 +9785,27 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 4beb09b4-d430-59c9-ad44-0708cfbc1825
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 6f4e8d0a-2b5c-4e7f-9a9d-1c0b2f3e4d5a
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
'410':
@@ -9565,7 +9846,10 @@ paths:
tags:
- Contacts
operationId: DeleteContact
- description: You can delete a single contact.
+ description: |
+ You can delete a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -9585,6 +9869,27 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 4631d568-2a95-5889-81c9-f779723578c9
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 8b6a0f2c-4d7e-4a9b-9c1f-3e2d4b5a6f7c
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
"/contacts/merge":
@@ -9598,7 +9903,7 @@ paths:
- name: include_merge_history
in: query
description: Pass `true` to include the merge history of the resulting contact
- in the response. Only returned for contacts with a `user` role.
+ in the response, with at most the 10 most recent merges.
required: false
schema:
type: boolean
@@ -9617,12 +9922,14 @@ paths:
{% admonition type="warning" name="Merged contacts are not retrievable via the API" %}
Once a merge is completed, the source contact (`from`) is permanently removed from the active contact list. This means:
- - **GET /contacts/{id}** — Requesting the source contact by its original ID will return `410 Gone` with a `Link` header pointing to the canonical (merged-into) contact.
+ - **GET /contacts/{id}** — Requesting the source contact by its original ID returns `410 Gone` with a `Link` header pointing to the contact it was merged into. See [Get a contact](/docs/references/rest-api/api.intercom.io/contacts/showcontact).
- **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 %}
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -9637,6 +9944,7 @@ paths:
external_id: '70'
role: user
email: joe@bloggs.com
+ email_domain: bloggs.com
email_verified: false
phone:
formatted_phone:
@@ -9719,6 +10027,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
allOf:
@@ -9756,6 +10066,42 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 3a3f8861-b1ec-52f1-856e-b1b9bb28275c
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 9c7b1a3d-5e8f-4b0c-8d2a-4f3e5c6b7a8d
+ errors:
+ - code: not_found
+ message: User Not Found
+ schema:
+ "$ref": "#/components/schemas/error"
+ '409':
+ description: Merge in progress
+ content:
+ application/json:
+ examples:
+ Merge in progress:
+ value:
+ type: error.list
+ request_id: 0d8c2b4e-6f9a-4c1d-9e3b-5a4f6d7c8b9e
+ errors:
+ - code: merge_in_progress
+ message: Merge already in progress for one of these contacts.
+ Please retry shortly.
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -9804,7 +10150,7 @@ paths:
| --- | --- |
| `source_same_as_target` | The source contact (`from`) and the destination contact (`into`) are the same contact. A contact can't be merged into itself. |
| `invalid_merge_role_pair` | The `from`/`into` roles aren't mergeable. `into` must be a user. |
- | `no_shared_identifier` | The contacts share no email or phone. Set `skip_duplicate_validation` to preview anyway. |
+ | `no_shared_identifier` | The contacts share no email or phone. The source's phone also counts as shared when it matches the destination's WhatsApp number. Set `skip_duplicate_validation` to preview anyway. |
| `facebook_user` | Facebook contacts can't be merged. |
| `external_lead_channel_not_allowed` | The source is an external-channel lead that isn't eligible for merging. |
| `mailing_list` | Contacts created from a mailing list can't be merged. |
@@ -9814,6 +10160,8 @@ paths:
| `ms_teams_data_cannot_be_merged` | The destination contact already has a Microsoft Teams sender for the same team as the source contact, so the source's sender can't be reassigned to it. |
| `source_has_telegram_data` | The source contact has Telegram data, which user-into-user merges don't yet support moving. |
| `phone_data_cannot_be_merged` | The phone data on the source contact can't be reassigned to the destination. |
+
+ Requires the `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -9868,7 +10216,7 @@ paths:
allowed: false
reasons:
- code: no_shared_identifier
- message: These contacts don't share a common identifier (email or phone), so they aren't recognised as duplicates. Set skip_duplicate_validation to true to preview the merge anyway.
+ message: These contacts don't share a common identifier (email, phone, or external ID), so they aren't recognised as duplicates. Set skip_duplicate_validation to true to preview the merge anyway.
schema:
"$ref": "#/components/schemas/merge_preview_response"
'401':
@@ -9883,6 +10231,27 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 5216a8fb-f031-5110-b19d-30868b50e550
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 1e9d3c5f-7a0b-4d2e-8f4c-6b5a7e8d9c0f
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -9906,12 +10275,23 @@ paths:
"$ref": "#/components/schemas/intercom_version"
- name: include_merge_history
in: query
- description: Pass `true` to include a `merge_history` array on each contact
- in the response. Only returned for contacts with a `user` role.
+ description: Pass `true` in the query string to include a `merge_history` array
+ on each contact in the response; a JSON boolean in the request body is ignored.
+ Returned for contacts of any role, with at most the 10 most recent merges.
required: false
schema:
type: boolean
default: false
+ - name: escape_identity
+ in: query
+ description: By default, `name` and `email` values in the response, including nested
+ ones such as social profile names, are HTML-escaped (for example, `&` is returned
+ as `&`). Custom attributes and tags are never escaped. Pass `false` to return
+ them unescaped.
+ required: false
+ schema:
+ type: boolean
+ default: true
tags:
- Contacts
operationId: SearchContacts
@@ -9942,6 +10322,8 @@ paths:
There are some limitations to the amount of multiple's there can be:
* There's a limit of max 2 nested filters
* There's a limit of max 15 filters for each AND or OR group
+ * There's a limit of max 15 values in an `IN` or `NIN` array
+ * `pagination.per_page` must be between 1 and 150
### Searching for Timestamp Fields
@@ -9962,7 +10344,7 @@ paths:
| Field | Type |
| ---------------------------------- | ------------------------------ |
| id | String |
- | role | String
Accepts user or lead |
+ | role | String
Accepts user or lead; contact is treated as lead |
| name | String |
| avatar | String |
| owner_id | Integer |
@@ -9981,6 +10363,7 @@ paths:
| last_email_clicked_at | Datetime (Unix timestamp in seconds) |
| language_override | String |
| browser | String |
+ | browser_version | String |
| browser_language | String |
| os | String |
| location.country | String |
@@ -9989,44 +10372,55 @@ paths:
| unsubscribed_from_emails | Boolean |
| marked_email_as_spam | Boolean |
| has_hard_bounced | Boolean |
+ | phone_country | String |
+ | slack_email | String |
+ | fin_qualification_status | String |
+ | whatsapp_number | String
Only on workspaces with the WhatsApp integration |
| ios_last_seen_at | Datetime (Unix timestamp in seconds) |
| ios_app_version | String |
| ios_device | String |
- | ios_app_device | String |
| ios_os_version | String |
| ios_app_name | String |
| ios_sdk_version | String |
| android_last_seen_at | Datetime (Unix timestamp in seconds) |
| android_app_version | String |
| android_device | String |
+ | android_os_version | String |
| android_app_name | String |
- | andoid_sdk_version | String |
+ | android_sdk_version | String |
+ | enabled_push_messaging | Boolean |
| segment_id | String |
| tag_id | String |
| custom_attributes.{attribute_name} | Matches the attribute's own type
(String, Integer, Float, Boolean or Date) |
+ The `ios_*` fields other than `ios_app_name` are searchable only once your workspace has been set up for the Intercom iOS SDK or has received a request from it, and the `android_*` fields other than `android_app_name` only once the same is true for the Android SDK. `enabled_push_messaging` needs either. Until then, they return an `invalid_field` error.
+
### Accepted Operators
{% admonition type="warning" name="Operators not supported on Date custom attributes" %}
- Date custom attributes do not support the `!=`, `>=`, or `<=` operators. Using them returns an error. Standard timestamp fields (`created_at`, `updated_at` etc.) do support these operators, and are filtered on the exact second.
+ Date custom attributes do not support the `!=`, `>=`, or `<=` operators. Using them returns a `422` error. Standard timestamp fields (`created_at`, `updated_at` etc.) do support these operators, and are filtered on the exact second.
{% /admonition %}
- The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). Which operators are valid depends on the field's type - see the "Valid Types" column below. Searching by `tag_id` supports only the `=` and `!=` operators.
+ The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). Which operators are valid depends on the field's type - see the "Valid Types" column below. Searching by `tag_id` or `segment_id` supports only the `=` and `!=` operators, with a single ID string as the value.
+
+ A `null` value is accepted only with `=` (matches Contacts with no value set) and `!=` (matches Contacts with any value set). An array value is accepted only with `IN` and `NIN`. String values must be shorter than 256 characters.
| Operator | Valid Types | Description |
| :------- | :---------------------------------- | :----------------------------------------------------------------------|
| = | All | Equals |
| != | All except Date | Doesn't Equal
Also matches Contacts with no value set |
- | IN | All except Date, Datetime and tag_id | In
Shortcut for `OR` queries
Values must be in Array |
- | NIN | All except Date, Datetime and tag_id | Not In
Shortcut for `OR !` queries
Values must be in Array |
- | > | Integer
Datetime
Date | Greater than
On Date custom attributes, matches from the start of the next day |
- | < | Integer
Datetime
Date | Lower than
On Date custom attributes, matches before the start of the day |
- | >= | Integer
Datetime | Greater than or equal to
Not supported on Date custom attributes |
- | <= | Integer
Datetime | Lower than or equal to
Not supported on Date custom attributes |
+ | IN | All except Date, Datetime, tag_id and segment_id | In
Shortcut for `OR` queries
Values must be in Array |
+ | NIN | All except Date, Datetime, tag_id and segment_id | Not In
Shortcut for `OR !` queries
Values must be in Array |
+ | > | Integer
Float
Datetime
Date | Greater than
On Date custom attributes, matches from the start of the next day |
+ | < | Integer
Float
Datetime
Date | Lower than
On Date custom attributes, matches before the start of the day |
+ | >= | Integer
Float
Datetime | Greater than or equal to
Not supported on Date custom attributes |
+ | <= | Integer
Float
Datetime | Lower than or equal to
Not supported on Date custom attributes |
| ~ | String | Contains |
| !~ | String | Doesn't Contain |
| ^ | String | Starts With |
| $ | String | Ends With |
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10057,6 +10451,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 648d4d57-2aa4-530b-909f-aad2c59197fe
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'400':
@@ -10071,6 +10472,63 @@ paths:
errors:
- code: invalid_sort_order
message: "Invalid sort order 'desc'. Must be one of: ascending, descending"
+ Invalid field:
+ value:
+ type: error.list
+ request_id: 3a7e2c91-5d4b-4f08-a6c3-9e1b7d2f4a60
+ errors:
+ - code: invalid_field
+ message: custom_attributes.plan_tier is not a valid search field
+ Invalid operator:
+ value:
+ type: error.list
+ request_id: 6b2f9d14-8e3a-4c57-b1d0-2a9c5e7f3b81
+ errors:
+ - code: invalid_operator
+ message: "email does not support operator: >"
+ Invalid value:
+ value:
+ type: error.list
+ request_id: 9c4a1e73-2b6d-4e98-a5f2-7d3b8c1e6a24
+ errors:
+ - code: invalid_value
+ message: Number of elements in composite query is greater than 15, please
+ try again with a smaller list
+ Invalid query:
+ value:
+ type: error.list
+ request_id: 1d8b5f26-7c3e-4a19-b2e4-5f6a9d0c8b37
+ errors:
+ - code: invalid_query
+ message: Query body must contain a query hash
+ Query nested too deeply:
+ value:
+ type: error.list
+ request_id: 4e9c2a58-1f7b-4d36-8a0e-3b5d7c9f1e42
+ errors:
+ - code: invalid_values
+ message: Value depth exceeds 2 items
+ Invalid per_page:
+ value:
+ type: error.list
+ request_id: 7f3d6b09-4a2c-4e85-9b1f-8c0e2d5a7b63
+ errors:
+ - code: invalid_per_page
+ message: per_page must be an integer between 0 and 150
+ schema:
+ "$ref": "#/components/schemas/error"
+ '422':
+ description: Unsupported operator on a Date custom attribute
+ content:
+ application/json:
+ examples:
+ Unsupported date comparison:
+ value:
+ type: error.list
+ request_id: 2c5e8a17-9d3f-4b60-a7c4-1e8f3b6d9a05
+ errors:
+ - code: data_invalid
+ message: "Date predicate doesn't support comparison type :ne"
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -10104,7 +10562,7 @@ paths:
- name: per_page
in: query
required: false
- description: The number of results to return per page. Defaults to 50, minimum 1, maximum 150.
+ description: The number of results to return per page. Defaults to 50, minimum 1, maximum 150; larger values are treated as `150`. Only the leading digits are read, so `1.5` is treated as `1`. A value that doesn't start with a positive integer, such as `0` or `abc`, returns a `400` error with code `invalid_per_page`.
schema:
type: integer
default: 50
@@ -10122,10 +10580,14 @@ paths:
description: |
You can fetch a list of contact activity events for your workspace, such as when contacts are created, role updated, merged, or deleted. Events are returned oldest first.
+ If the activity store can't be read, this endpoint returns `200` with an empty `data` array and no `pages.next`, the same response as when there are no new events.
+
{% admonition type="warning" name="Pagination" %}
You can use pagination to limit the number of results returned. The default is `50` results per page, with a maximum of `150`.
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.
{% /admonition %}
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10175,11 +10637,25 @@ paths:
created_at: 1717000400
pages:
type: pages
- per_page: 50
+ per_page: 5
next:
starting_after: '1717000400000.0000e5'
schema:
"$ref": "#/components/schemas/contact_activity_list"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Invalid per_page:
+ value:
+ type: error.list
+ request_id: 5a1c7e39-6b2d-4f84-9e0a-3c8d1f5b7a26
+ errors:
+ - code: invalid_per_page
+ message: per_page must be a positive integer
+ schema:
+ "$ref": "#/components/schemas/error"
'401':
description: Unauthorized
content:
@@ -10192,6 +10668,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 3aa05fbd-7443-55e1-9b80-7766454b008d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts":
@@ -10205,11 +10688,42 @@ paths:
- name: include_merge_history
in: query
description: Pass `true` to include a `merge_history` array on each contact
- in the response. Only returned for contacts with a `user` role.
+ in the response. Returned for contacts of any role, with at most the 10 most
+ recent merges.
required: false
schema:
type: boolean
default: false
+ - name: escape_identity
+ in: query
+ description: By default, `name` and `email` values in the response, including nested
+ ones such as social profile names, are HTML-escaped (for example, `&` is returned
+ as `&`). Custom attributes and tags are never escaped. Pass `false` to return
+ them unescaped.
+ required: false
+ schema:
+ type: boolean
+ default: true
+ - name: per_page
+ in: query
+ description: The number of results per page. Defaults to `10`, with a maximum
+ of `150`; larger values are treated as `150`. Only the leading digits are read,
+ so `1.5` is treated as `1`. A value that doesn't start with a positive integer,
+ such as `0` or `abc`, returns a `400` error with code `invalid_per_page`.
+ required: false
+ schema:
+ type: integer
+ minimum: 1
+ default: 10
+ maximum: 150
+ - name: starting_after
+ in: query
+ description: The cursor value from `pages.next.starting_after` in a previous
+ response. An empty value is ignored. A value that isn't a valid cursor returns
+ a `400` error with code `client_error`.
+ required: false
+ schema:
+ type: string
tags:
- Contacts
operationId: ListContacts
@@ -10222,6 +10736,8 @@ paths:
You can use pagination to limit the number of results returned. The default is `10` results per page, with a maximum of `150`.
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.
{% /admonition %}
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10252,6 +10768,34 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: e3b9f9b0-51d9-5926-bca5-4f5b6c9a3e5c
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Invalid per_page:
+ value:
+ type: error.list
+ request_id: 0b6e3d82-5f1a-4c97-a2d8-6e9f4b1c3a75
+ errors:
+ - code: invalid_per_page
+ message: per_page must be a positive integer
+ Invalid starting_after:
+ value:
+ type: error.list
+ request_id: 8e2a4c61-3d7f-4b05-9c1e-5a8b2f6d0e94
+ errors:
+ - code: client_error
+ message: Invalid starting_after param. Please try again using a starting_after value from a paginated response
schema:
"$ref": "#/components/schemas/error"
post:
@@ -10264,7 +10808,10 @@ paths:
tags:
- Contacts
operationId: CreateContact
- description: You can create a new contact (ie. user or lead).
+ description: |
+ You can create a new contact (ie. user or lead).
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -10279,6 +10826,7 @@ paths:
external_id:
role: user
email: joebloggs@intercom.io
+ email_domain: intercom.io
email_verified: false
phone:
formatted_phone:
@@ -10361,6 +10909,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
allOf:
@@ -10383,6 +10933,101 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: ae05b405-0bc7-5a7f-b519-0bcb15655216
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Invalid timestamp:
+ value:
+ type: error.list
+ request_id: 9d3b7f15-2c8e-4a61-b4d9-0e5f2a7c1b38
+ errors:
+ - code: parameter_invalid
+ message: "'signed_up_at' appears to be in milliseconds. Timestamps
+ must be Unix timestamps in seconds."
+ Owner not a teammate:
+ value:
+ type: error.list
+ request_id: 1e4c8a26-3d9f-4b72-a5e0-7f6a3b8d2c49
+ errors:
+ - code: parameter_invalid
+ message: The owner specified is not a member of the app
+ Custom attribute does not exist:
+ value:
+ type: error.list
+ request_id: 2f5d9b37-4e0a-4c83-b6f1-8a7b4c9e3d50
+ errors:
+ - code: parameter_invalid
+ message: Custom attribute 'plan_tier' does not exist
+ Invalid custom attributes:
+ value:
+ type: error.list
+ request_id: 3a6e0c48-5f1b-4d94-87a2-9b8c5d0f4e61
+ errors:
+ - code: nested_custom_attributes
+ message: "'custom_attributes' must be an object"
+ schema:
+ "$ref": "#/components/schemas/error"
+ '409':
+ description: Contact already exists
+ content:
+ application/json:
+ examples:
+ Contact already exists:
+ value:
+ type: error.list
+ request_id: 4b7f1d59-6a2c-4ea5-98b3-0c9d6e1a5f72
+ errors:
+ - code: conflict
+ message: A contact matching those details already exists with
+ id=6762f0dd1bb69f9f2193bb83
+ Archived contact already exists:
+ value:
+ type: error.list
+ request_id: 5c8a2e6a-7b3d-4fb6-89c4-1d0e7f2b6a83
+ errors:
+ - code: conflict
+ message: An archived contact matching those details already
+ exists with id=6762f0dd1bb69f9f2193bb83
+ Multiple matching contacts:
+ value:
+ type: error.list
+ request_id: 2d7b9e41-6c3a-4f08-b5d2-9a1e7c4f0b63
+ errors:
+ - code: conflict
+ message: Multiple contacts matching those details already exists
+ with id= email=joe@example.com
+ Contact created at the same time:
+ value:
+ type: error.list
+ request_id: 6f1a3c8e-9d2b-4a75-8e40-b3c6d1f9a082
+ errors:
+ - code: conflict
+ message: A contact matching those details already exists
+ schema:
+ "$ref": "#/components/schemas/error"
+ '422':
+ description: Unprocessable Entity
+ content:
+ application/json:
+ examples:
+ Invalid email:
+ value:
+ type: error.list
+ request_id: 6d9b3f7b-8c4e-4ac7-9ad5-2e1f8a3c7b94
+ errors:
+ - code: parameter_invalid
+ message: "'email' is not a valid email address."
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -10414,11 +11059,21 @@ paths:
- name: include_merge_history
in: query
description: Pass `true` to include the contact's merge history in the response.
- Only returned for contacts with a `user` role.
+ Returned for contacts of any role, with at most the 10 most recent merges.
required: false
schema:
type: boolean
default: false
+ - name: escape_identity
+ in: query
+ description: By default, `name` and `email` values in the response, including nested
+ ones such as social profile names, are HTML-escaped (for example, `&` is returned
+ as `&`). Custom attributes and tags are never escaped. Pass `false` to return
+ them unescaped.
+ required: false
+ schema:
+ type: boolean
+ default: true
tags:
- Contacts
operationId: ShowContactByExternalId
@@ -10428,6 +11083,8 @@ paths:
{% admonition type="info" name="Merged contacts return 410 Gone" %}
If the contact with this external ID has been merged into another contact, the API returns **HTTP 410 Gone** with a `Link` header pointing to the canonical (merged-into) contact. See `GET /contacts/{id}` for details on the response format.
{% /admonition %}
+
+ Requires the `read_single_user`, `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10442,6 +11099,7 @@ paths:
external_id: '70'
role: user
email: joe@bloggs.com
+ email_domain: bloggs.com
email_verified: false
phone:
formatted_phone:
@@ -10524,6 +11182,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
allOf:
@@ -10546,6 +11206,27 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: c3ae8c73-bd9a-5a00-b68c-fc7c932d59a8
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 7a5f9e1b-3c6d-4f8a-8b0e-2d1c3a4f5e6b
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
'410':
@@ -10588,7 +11269,10 @@ paths:
tags:
- Contacts
operationId: ArchiveContact
- description: You can archive a single contact.
+ description: |
+ You can archive a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -10596,6 +11280,22 @@ paths:
application/json:
schema:
"$ref": "#/components/schemas/contact_archived"
+ '401':
+ "$ref": "#/components/responses/Unauthorized"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 8d6c0b2e-4f7a-4c9d-9e1b-3a2f4d5c6b7e
+ errors:
+ - code: not_found
+ message: User Not Found
+ schema:
+ "$ref": "#/components/schemas/error"
"/contacts/{id}/unarchive":
post:
summary: Unarchive contact
@@ -10614,7 +11314,10 @@ paths:
tags:
- Contacts
operationId: UnarchiveContact
- description: You can unarchive a single contact.
+ description: |
+ You can unarchive a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -10622,6 +11325,60 @@ paths:
application/json:
schema:
"$ref": "#/components/schemas/contact_unarchived"
+ '400':
+ description: Contact can't be restored
+ content:
+ application/json:
+ examples:
+ Blocked contact:
+ value:
+ type: error.list
+ request_id: 9e7d1c3f-5a8b-4d0e-8f2c-4b3a5e6d7c8f
+ errors:
+ - code: not_restorable
+ message: User has been blocked and is not restorable. See your
+ App blocked user list for more detail.
+ Merged contact:
+ value:
+ type: error.list
+ request_id: 0f8e2d4a-6b9c-4e1f-9a3d-5c4b6f7e8d9a
+ errors:
+ - code: bad_request
+ message: User has been merged and is not restorable.
+ Pending permanent deletion:
+ value:
+ type: error.list
+ request_id: 1a9f3e5b-7c0d-4f2a-8b4e-6d5c7a8f9e0b
+ errors:
+ - code: bad_request
+ message: User has been marked for permanent deletion and is not
+ restorable.
+ Duplicate contact:
+ value:
+ type: error.list
+ request_id: 2b0a4f6c-8d1e-4a3b-9c5f-7e6d8b9a0f1c
+ errors:
+ - code: unique_user_constraint
+ message: This user is archived but cannot be restored because
+ another user exists with this email or user_id.
+ schema:
+ "$ref": "#/components/schemas/error"
+ '401':
+ "$ref": "#/components/responses/Unauthorized"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 3c1b5a7d-9e2f-4b4c-8d6a-8f7e9c0b1a2d
+ errors:
+ - code: not_found
+ message: User Not Found
+ schema:
+ "$ref": "#/components/schemas/error"
"/contacts/{id}/block":
post:
summary: Block contact
@@ -10640,7 +11397,10 @@ paths:
tags:
- Contacts
operationId: BlockContact
- description: Block a single contact.
**Note:** conversations of the contact will also be archived during the process.
More details in [FAQ How do I block Inbox spam?](https://www.intercom.com/help/en/articles/8838656-inbox-faqs)
+ description: |
+ Block a single contact.
**Note:** conversations of the contact will also be archived during the process.
More details in [FAQ How do I block Inbox spam?](https://www.intercom.com/help/en/articles/8838656-inbox-faqs)
+
+ Requires the `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10648,6 +11408,29 @@ paths:
application/json:
schema:
"$ref": "#/components/schemas/contact_blocked"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 4d2c6b8e-0f3a-4c5d-9e7b-9a8f0d1c2b3e
+ errors:
+ - code: parameter_invalid
+ message: The user 63a07ddf05a32042dffac965 could not be found
+ Company email address:
+ value:
+ type: error.list
+ request_id: 5e3d7c9f-1a4b-4d6e-8f8c-0b9a1e2d3c4f
+ errors:
+ - code: parameter_invalid
+ message: The user 63a07ddf05a32042dffac965 has a company email address
+ schema:
+ "$ref": "#/components/schemas/error"
+ '401':
+ "$ref": "#/components/responses/Unauthorized"
"/contacts/{id}/merge_histories":
get:
summary: Get contact merge history
@@ -10672,7 +11455,8 @@ paths:
type: string
- name: per_page
in: query
- description: The number of results to return per page (default 50, max 150).
+ description: The number of results to return per page (default 50, max 150). A value
+ outside 1–150 returns a `422` error.
required: false
schema:
type: integer
@@ -10681,7 +11465,8 @@ paths:
maximum: 150
- name: order
in: query
- description: The order to return results in. Defaults to descending.
+ description: The order to return results in. Defaults to descending. Any other value
+ returns a `422` error.
required: false
schema:
type: string
@@ -10695,6 +11480,8 @@ paths:
Retrieve the paginated list of contacts that have been merged into a given contact.
Only available for contacts with a `user` role. Returns a `404` if the contact is not found or has a `lead` role.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10725,6 +11512,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 69c5df7c-0c2b-5596-90f6-b3b636ea51c8
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'404':
@@ -10738,7 +11532,34 @@ paths:
request_id: 45b30bd1-75d2-40cc-bb39-74ac133a2836
errors:
- code: not_found
- message: Contact not found
+ message: User Not Found
+ Contact is not a user:
+ value:
+ type: error.list
+ errors:
+ - code: not_found
+ message: Not Found
+ schema:
+ "$ref": "#/components/schemas/error"
+ '422':
+ description: Invalid parameter
+ content:
+ application/json:
+ examples:
+ Invalid per_page:
+ value:
+ type: error.list
+ request_id:
+ errors:
+ - code: parameter_invalid
+ message: Limit is too big
+ Invalid cursor:
+ value:
+ type: error.list
+ request_id:
+ errors:
+ - code: parameter_invalid
+ message: must be a valid base64-encoded JSON cursor
schema:
"$ref": "#/components/schemas/error"
"/contacts/{id}/banners":
@@ -10767,6 +11588,8 @@ paths:
with the dismiss endpoint. A returned banner is treated as shown: requesting
this endpoint records an impression for each banner returned, so call it at the
point you are about to display the banners, not speculatively.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: Successful response
@@ -10790,6 +11613,8 @@ paths:
created_at: 1780580493
schema:
"$ref": "#/components/schemas/banner_list"
+ '401':
+ "$ref": "#/components/responses/Unauthorized"
'404':
description: Contact not found
content:
@@ -10835,6 +11660,8 @@ paths:
The request is idempotent: dismissing an already-dismissed banner succeeds and
returns the same response.
+
+ Requires the `read_write_users` OAuth scope.
responses:
'200':
description: Successful response
@@ -10848,8 +11675,10 @@ paths:
dismissed: true
schema:
"$ref": "#/components/schemas/banner_dismiss"
+ '401':
+ "$ref": "#/components/responses/Unauthorized"
'404':
- description: Banner view not found
+ description: Banner view or contact not found
content:
application/json:
examples:
@@ -10860,6 +11689,13 @@ paths:
errors:
- code: not_found
message: Resource Not Found
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 8a2d6f0e-4b7c-4e19-9f3a-1c5e8b2d7f46
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
"/contacts/bulk":
@@ -10891,6 +11727,8 @@ paths:
- You can append tasks to an existing job by including `job.id` in the request body.
- Tag application is best-effort and processed asynchronously: unknown tag IDs are skipped, and per-tag results are not returned in the job status.
{% /admonition %}
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
requestBody:
content:
application/json:
@@ -10985,6 +11823,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 941c4b1b-d76e-5cd5-a1bb-6d69ad1905ed
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'403':
@@ -11072,6 +11917,8 @@ paths:
- You can append tasks to an existing job by including `job.id` in the request body.
- Tag application is best-effort and processed asynchronously: unknown tag IDs are skipped, and per-tag results are not returned in the job status.
{% /admonition %}
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
requestBody:
content:
application/json:
@@ -11173,6 +12020,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 1a6d2e20-cdad-5c98-a063-26454d9eb71d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'403':
@@ -11269,6 +12123,8 @@ paths:
- Maximum of 100 contacts per request.
- You can append tasks to an existing job by including `job.id` in the request body.
{% /admonition %}
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
requestBody:
content:
application/json:
@@ -11324,6 +12180,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: a4abbb6a-8868-585e-be5b-b068a3dd5fd0
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'403':
@@ -11415,7 +12278,9 @@ paths:
- Contacts
operationId: ShowBulkUpdateContactsJob
description: |
- You can check the status of a bulk contact update job. The `state` field indicates the overall job progress: `pending`, `running`, `completed`, or `completed_with_errors`.
+ You can check the status of a bulk contact update job. The `state` field indicates the overall job progress: `running`, `completed`, or `completed_with_errors`.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -11452,6 +12317,27 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: e4462db2-6098-589c-b6b4-3f6c6e8f2250
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Job not found
+ content:
+ application/json:
+ examples:
+ Job not found:
+ value:
+ type: error.list
+ request_id: 7e0c4a8d-9d5f-4bd8-8be6-3f2a9b4d8c05
+ errors:
+ - code: not_found
+ message: Resource Not Found
schema:
"$ref": "#/components/schemas/error"
"/content/bulk_actions":
@@ -27964,6 +28850,7 @@ paths:
external_id:
role: user
email: foo@bar.com
+ email_domain: bar.com
email_verified: false
phone:
formatted_phone:
@@ -28046,6 +28933,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
"$ref": "#/components/schemas/contact"
@@ -33488,7 +34377,7 @@ components:
email_verified:
type: boolean
description: >-
- Whether the contact has proved they own their current email address. `true` only when this address was marked verified through the Contacts API (`email_verified: true` on create or update) and has not changed since; it becomes `false` again if the contact's email changes, until the new address is verified. Intercom reuses a lead with a verified email when it later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. Only returned on the Preview version; not present on any released API version.
+ Whether the contact has proved they own their current email address. `true` only when this address was marked verified through the Contacts API (`email_verified: true` on create or update) and has not changed since; it becomes `false` again if the contact's email changes, until the new address is verified. Intercom reuses a lead with a verified email when it later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. In List contacts and Search contacts responses it is left out only if the contact can't be loaded, for example when it is deleted while the request runs.
example: true
phone:
type: string
@@ -33673,19 +34562,11 @@ components:
type: object
description: The custom attributes which are set for the contact.
avatar:
- type: object
+ type: string
+ format: uri
nullable: true
- properties:
- type:
- type: string
- description: The type of object
- example: avatar
- image_url:
- type: string
- format: uri
- nullable: true
- description: An image URL containing the avatar of a contact.
- example: https://example.org/128Wash.jpg
+ description: An image URL containing the avatar of a contact.
+ example: https://example.org/128Wash.jpg
tags:
"$ref": "#/components/schemas/contact_tags"
notes:
@@ -33696,12 +34577,59 @@ components:
"$ref": "#/components/schemas/contact_location"
social_profiles:
"$ref": "#/components/schemas/contact_social_profiles"
+ opted_out_subscription_types:
+ "$ref": "#/components/schemas/contact_subscription_types"
+ opted_in_subscription_types:
+ "$ref": "#/components/schemas/contact_subscription_types"
+ utm_campaign:
+ type: string
+ nullable: true
+ description: The `utm_campaign` value recorded for the contact.
+ example: spring_launch
+ utm_content:
+ type: string
+ nullable: true
+ description: The `utm_content` value recorded for the contact.
+ example: banner_ad
+ utm_medium:
+ type: string
+ nullable: true
+ description: The `utm_medium` value recorded for the contact.
+ example: email
+ utm_source:
+ type: string
+ nullable: true
+ description: The `utm_source` value recorded for the contact.
+ example: newsletter
+ utm_term:
+ type: string
+ nullable: true
+ description: The `utm_term` value recorded for the contact.
+ example: support_software
+ referrer:
+ type: string
+ nullable: true
+ description: The URL of the page the contact came from, as recorded by the Messenger.
+ example: https://example.com/pricing
+ sms_consent:
+ type: boolean
+ description: Whether the contact has consented to receive SMS messages.
+ example: false
+ unsubscribed_from_sms:
+ type: boolean
+ description: Whether the contact is unsubscribed from SMS messages.
+ example: false
+ enabled_push_messaging:
+ type: boolean
+ nullable: true
+ description: Whether the contact has a mobile device registered to receive push messages.
+ example: true
merge_history:
type: array
nullable: true
- description: A list of contacts that were merged into this contact. Only
- included in the response when `include_merge_history=true` is passed as
- a query parameter. Only available for contacts with a `user` role.
+ description: A list of contacts that were merged into this contact, most
+ recent first, capped at 10. Only included in the response when
+ `include_merge_history=true` is passed as a query parameter.
items:
"$ref": "#/components/schemas/merge_history_item"
merge_history_item:
@@ -33750,7 +34678,7 @@ components:
type: string
nullable: true
description: A cursor to pass as the `cursor` query parameter to fetch
- the next page of results. Absent when there are no more pages.
+ the next page of results. `null` when there are no more pages.
example: WyIxNjM0NTY3ODkwIl0
has_more:
type: boolean
@@ -33767,7 +34695,7 @@ components:
enum:
- list
example: list
- companies:
+ data:
type: array
description: An array containing Company Objects
items:
@@ -33865,28 +34793,23 @@ components:
example: 6329bd9ffe4e2e91dc5d6a1e
external_id:
type: string
- nullable: true
- description: The external identifier of the contact, if one is set.
+ description: The external identifier of the contact. Omitted when not set.
example: user-42
role:
type: string
- nullable: true
- description: The role of the contact at the time of the event, either user, lead, or visitor.
+ description: The role of the contact at the time of the event, either user, lead, or visitor. Omitted when not recorded.
example: user
merge_source_id:
type: string
- nullable: true
- description: For merge events, the identifier of the contact that was merged away.
+ description: For merge events, the identifier of the contact that was merged away. Omitted on other events.
example: 5f7f0d217c3f2e001a4e8b12
merge_target_id:
type: string
- nullable: true
- description: For merge events, the identifier of the contact that was merged into.
+ description: For merge events, the identifier of the contact that was merged into. Omitted on other events.
example: 6329bd9ffe4e2e91dc5d6a1e
failure_reason:
type: string
- nullable: true
- description: For failed events, the reason the activity did not succeed.
+ description: For failed events, the reason the activity did not succeed. Omitted on other events.
example: duplicate_external_id
created_at:
type: integer
@@ -33924,8 +34847,7 @@ components:
example: 10
next:
type: object
- nullable: true
- description: Cursor for the next page of results.
+ description: Cursor for the next page of results. Omitted on the last page.
properties:
starting_after:
type: string
@@ -34065,7 +34987,6 @@ components:
type: string
description: The current state of the job.
enum:
- - pending
- running
- completed
- completed_with_errors
@@ -34084,8 +35005,9 @@ components:
type: integer
format: date-time
nullable: true
- description: The time the job completed as a UNIX timestamp. Null if not
- yet completed.
+ description: The time the most recent task completed as a Unix timestamp.
+ Set as soon as any task completes, so check `state` to know whether
+ the whole job has finished. Null until a task completes.
example: 1713360120
tasks:
type: array
@@ -34159,6 +35081,16 @@ components:
nullable: true
description: The city that the contact is located in
example: Dublin
+ country_code:
+ type: string
+ nullable: true
+ description: The ISO 3166-1 alpha-3 code of the country that the contact is located in
+ example: IRL
+ continent_code:
+ type: string
+ nullable: true
+ description: The code of the continent that the contact is located in
+ example: EU
contact_notes:
title: Contact notes
type: object
@@ -34438,6 +35370,12 @@ components:
description: An object containing Subscription Types meta data about the SubscriptionTypes
that a contact has.
properties:
+ type:
+ type: string
+ description: The type of the object
+ enum:
+ - list
+ example: list
data:
type: array
description: This object represents the subscriptions attached to a contact.
@@ -37184,7 +38122,7 @@ components:
properties:
role:
type: string
- description: The role of the contact.
+ description: The role of the contact. `lead` creates a lead; any other value creates a user.
example: user
external_id:
type: string
@@ -37241,6 +38179,14 @@ components:
nullable: true
description: Whether the contact is unsubscribed from emails
example: true
+ sms_consent:
+ type: boolean
+ description: Whether the contact has consented to receive SMS messages.
+ example: false
+ unsubscribed_from_sms:
+ type: boolean
+ description: Whether the contact is unsubscribed from SMS messages.
+ example: false
language_override:
type: string
nullable: true
@@ -43406,7 +44352,7 @@ components:
properties:
attributes:
type: array
- description: The individual attribute changes. Capped at 50 items; total_count reflects the full number of changes.
+ description: The individual attribute changes. At most 50 custom attribute changes are included; changes to standard fields are always included, so this array can hold more than 50 items. total_count reflects the full number of changes.
items:
"$ref": "#/components/schemas/merge_preview_attribute_change"
total_count:
@@ -46499,7 +47445,8 @@ components:
properties:
role:
type: string
- description: The role of the contact.
+ description: The role of the contact, either `user` or `lead`. Any other value is ignored.
+ A user can't be changed to a lead; sending `lead` for a user returns a `400` error.
external_id:
type: string
description: A unique identifier for the contact which is given to Intercom
@@ -46554,6 +47501,14 @@ components:
nullable: true
description: Whether the contact is unsubscribed from emails
example: true
+ sms_consent:
+ type: boolean
+ description: Whether the contact has consented to receive SMS messages.
+ example: false
+ unsubscribed_from_sms:
+ type: boolean
+ description: Whether the contact is unsubscribed from SMS messages.
+ example: false
language_override:
type: string
nullable: true
diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml
index dce133b3..0b6821c2 100644
--- a/descriptions/2.17/api.intercom.io.yaml
+++ b/descriptions/2.17/api.intercom.io.yaml
@@ -8138,13 +8138,17 @@ paths:
in: path
required: true
description: The unique identifier for the contact which is given by Intercom
+ example: 58a430d35458202d41b1e65b
schema:
type: string
tags:
- Companies
- Contacts
operationId: attachContactToACompany
- description: You can attach a company to a single contact.
+ description: |
+ You can attach a company to a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -8172,6 +8176,12 @@ paths:
segments: []
plan: {}
custom_attributes: {}
+ notes:
+ type: note.list
+ data: []
+ url: "/companies/6762f09a1bb69f9f2193bb34/notes"
+ total_count: 0
+ has_more: false
schema:
"$ref": "#/components/schemas/company"
'400':
@@ -8196,7 +8206,7 @@ paths:
schema:
"$ref": "#/components/schemas/error"
'404':
- description: Company Not Found
+ description: Company Not Found or Contact Not Found
content:
application/json:
examples:
@@ -8207,6 +8217,13 @@ paths:
errors:
- code: company_not_found
message: Company Not Found
+ Contact Not Found:
+ value:
+ type: error.list
+ request_id: 7b1f5e2c-19c8-4c7f-9f0a-6f0a6a0ad3c1
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
'401':
@@ -8221,6 +8238,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 1daf6d3f-99ba-59c7-86f7-5d966270f7d3
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -8262,6 +8286,36 @@ paths:
in: header
schema:
"$ref": "#/components/schemas/intercom_version"
+ - name: page
+ in: query
+ required: false
+ description: The page of results to fetch. Values below 1 are treated as 1.
+ schema:
+ type: integer
+ default: 1
+ example: 1
+ - name: per_page
+ in: query
+ required: false
+ description: The number of companies to return per page. The maximum is 60; a value above
+ 60 returns a `400` error with code `parameter_invalid`.
+ schema:
+ type: integer
+ default: 50
+ maximum: 60
+ example: 50
+ - name: order
+ in: query
+ required: false
+ description: The order of the companies by when they were last active (`last_request_at`).
+ The value is case-insensitive, and any value other than `asc` is treated as `desc`.
+ schema:
+ type: string
+ enum:
+ - asc
+ - desc
+ default: desc
+ example: desc
tags:
- Contacts
- Companies
@@ -8297,6 +8351,12 @@ paths:
segments: []
plan: {}
custom_attributes: {}
+ notes:
+ type: note.list
+ data: []
+ url: "/companies/6762f0a61bb69f9f2193bb55/notes"
+ total_count: 0
+ has_more: false
pages:
type: pages
next:
@@ -8306,6 +8366,20 @@ paths:
total_count: 1
schema:
"$ref": "#/components/schemas/contact_attached_companies"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Per page too big:
+ value:
+ type: error.list
+ request_id: 3f1c2b9e-6a4d-4c8e-9b7a-2d5e8f0a1c34
+ errors:
+ - code: parameter_invalid
+ message: Per Page is too big
+ schema:
+ "$ref": "#/components/schemas/error"
'404':
description: Contact not found
content:
@@ -8360,7 +8434,10 @@ paths:
- Companies
- Contacts
operationId: detachContactFromACompany
- description: You can detach a company from a single contact.
+ description: |
+ You can detach a company from a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -8388,10 +8465,16 @@ paths:
segments: []
plan: {}
custom_attributes: {}
+ notes:
+ type: note.list
+ data: []
+ url: "/companies/6762f0a01bb69f9f2193bb44/notes"
+ total_count: 0
+ has_more: false
schema:
"$ref": "#/components/schemas/company"
'404':
- description: Contact Not Found
+ description: Company Not Found or Contact Not Found
content:
application/json:
examples:
@@ -8423,6 +8506,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 11900fce-9e5c-5d21-84d5-5bcf188287fd
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts/{contact_id}/notes":
@@ -8637,7 +8727,10 @@ paths:
- Contacts
- Segments
operationId: listSegmentsForAContact
- description: You can fetch a list of segments that are associated to a contact.
+ description: |
+ You can fetch a list of segments that are associated to a contact.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -8682,6 +8775,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: ca383411-d6ac-5db4-9c4d-352b36f69c8d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts/{contact_id}/subscriptions":
@@ -8807,6 +8907,8 @@ paths:
2.Attaching a contact to an opt-in subscription type will opt that user in to receiving messages related to that subscription type.
This will return a subscription type model for the subscription type that was added to the contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -8864,6 +8966,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 82051728-b8a8-5bfd-9f10-71f9a1dc3107
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -8873,7 +8982,6 @@ paths:
type: object
required:
- id
- - consent_type
properties:
id:
type: string
@@ -8882,7 +8990,8 @@ paths:
example: '37846'
consent_type:
type: string
- description: The consent_type of a subscription, opt_out or opt_in.
+ description: Ignored. Whether the contact is opted in or out is decided
+ by the subscription type's own `consent_type`, not by this value.
example: opt_in
examples:
successful:
@@ -8927,9 +9036,12 @@ paths:
schema:
type: string
operationId: detachSubscriptionTypeToContact
- description: You can remove a specific subscription from a contact. This will
+ description: |
+ You can remove a specific subscription from a contact. This will
return a subscription type model for the subscription type that was removed
from the contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: Successful
@@ -8987,6 +9099,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 9c562afa-93d0-53d2-bfa4-bb6463fa84ee
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts/{contact_id}/tags":
@@ -9075,8 +9194,11 @@ paths:
schema:
type: string
operationId: attachTagToContact
- description: You can tag a specific contact. This will return a tag object for
+ description: |
+ You can tag a specific contact. This will return a tag object for
the tag that was added to the contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -9127,6 +9249,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 42e197b1-6bc2-5504-915d-97e9e59f6c28
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -9146,11 +9275,11 @@ paths:
successful:
summary: successful
value:
- id: 81
+ id: '81'
contact_not_found:
summary: Contact not found
value:
- id: 82
+ id: '82'
tag_not_found:
summary: Tag not found
value:
@@ -9181,8 +9310,11 @@ paths:
schema:
type: string
operationId: detachTagFromContact
- description: You can remove tag from a specific contact. This will return a
+ description: |
+ You can remove tag from a specific contact. This will return a
tag object for the tag that was removed from the contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -9233,6 +9365,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: c6d0888c-4330-545c-8476-656828fed13d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts/deleted":
@@ -9246,7 +9385,9 @@ paths:
- name: per_page
in: query
description: The number of results per page. Defaults to `10`, with a maximum
- of `150`.
+ of `150`; larger values are treated as `150`. Only the leading digits are read,
+ so `1.5` is treated as `1`. A value that doesn't start with a positive integer,
+ such as `0` or `abc`, returns a `400` error with code `invalid_per_page`.
required: false
schema:
type: integer
@@ -9261,6 +9402,14 @@ paths:
type: integer
minimum: 1
default: 1
+ - name: escape_identity
+ in: query
+ description: By default, `email` values in the response are HTML-escaped (for example,
+ `&` is returned as `&`). Pass `false` to return them unescaped.
+ required: false
+ schema:
+ type: boolean
+ default: true
tags:
- Contacts
operationId: listDeletedContacts
@@ -9271,6 +9420,8 @@ paths:
is inactive: `archived`, `blocked`, `merged`, `pending_deletion`, or `permanently_deleted`.
`merged_into_id` is present only when `status` is `merged`, and `external_id` and `email`
are `null` for `permanently_deleted` contacts.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -9323,6 +9474,13 @@ paths:
errors:
- code: invalid_page
message: page must be a positive integer
+ Invalid per_page:
+ value:
+ type: error.list
+ request_id: 7b2c3d4e-5f6a-4b8c-9d0e-1f2a3b4c5d6e
+ errors:
+ - code: invalid_per_page
+ message: per_page must be a positive integer
schema:
"$ref": "#/components/schemas/error"
'401':
@@ -9337,6 +9495,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 4cd97183-4b6b-5eb9-a020-439cc6964338
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts/{contact_id}":
@@ -9357,7 +9522,7 @@ paths:
- name: include_merge_history
in: query
description: Pass `true` to include the contact's merge history in the response.
- Only returned for contacts with a `user` role.
+ Returned for contacts of any role, with at most the 10 most recent merges.
required: false
schema:
type: boolean
@@ -9374,6 +9539,8 @@ paths:
See _`update a contact with an association to a custom object instance`_ in the request/response examples to see the custom object association format.
{% /admonition %}
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -9388,6 +9555,7 @@ paths:
external_id: '70'
role: user
email: joebloggs@intercom.io
+ email_domain: intercom.io
email_verified: false
phone:
name: joe bloggs
@@ -9468,6 +9636,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
update a contact with an association to a custom object instance:
value:
@@ -9477,6 +9647,7 @@ paths:
external_id: '70'
role: user
email: joebloggs@intercom.io
+ email_domain: intercom.io
email_verified: false
phone:
name: joe bloggs
@@ -9568,6 +9739,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
allOf:
@@ -9590,6 +9763,84 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 186669b6-de99-567c-91ac-c5d9e513b0a6
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Invalid timestamp:
+ value:
+ type: error.list
+ request_id: 2d0c4b6e-8f1a-4c3d-9e5b-7a6f8d9c0b1e
+ errors:
+ - code: parameter_invalid
+ message: "'signed_up_at' appears to be in milliseconds. Timestamps
+ must be Unix timestamps in seconds."
+ Owner not a teammate:
+ value:
+ type: error.list
+ request_id: 3e1d5c7f-9a2b-4d4e-8f6c-8b7a9e0d1c2f
+ errors:
+ - code: parameter_invalid
+ message: The owner specified is not a member of the app
+ Custom attribute does not exist:
+ value:
+ type: error.list
+ request_id: 4f2e6d8a-0b3c-4e5f-9a7d-9c8b0f1e2d3a
+ errors:
+ - code: parameter_invalid
+ message: Custom attribute 'plan_tier' does not exist
+ Invalid custom attributes:
+ value:
+ type: error.list
+ request_id: 5a3f7e9b-1c4d-4f6a-8b8e-0d9c1a2f3e4b
+ errors:
+ - code: nested_custom_attributes
+ message: "'custom_attributes' must be an object"
+ User can't become a lead:
+ value:
+ type: error.list
+ request_id: 8e4c2a6f-3b7d-4e9a-a1c5-6f0d2b8e4a37
+ errors:
+ - code: client_error
+ message: Contact with user role can't be converted to a lead
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 6b4a8f0c-2d5e-4a7b-9c9f-1e0d2b3a4f5c
+ errors:
+ - code: not_found
+ message: User Not Found
+ schema:
+ "$ref": "#/components/schemas/error"
+ '422':
+ description: Unprocessable Entity
+ content:
+ application/json:
+ examples:
+ Invalid email:
+ value:
+ type: error.list
+ request_id: 7c5b9a1d-3e6f-4b8c-8d0a-2f1e3c4b5a6d
+ errors:
+ - code: parameter_invalid
+ message: "'email' is not a valid email address."
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -9628,11 +9879,21 @@ paths:
- name: include_merge_history
in: query
description: Pass `true` to include the contact's merge history in the response.
- Only returned for contacts with a `user` role.
+ Returned for contacts of any role, with at most the 10 most recent merges.
required: false
schema:
type: boolean
default: false
+ - name: escape_identity
+ in: query
+ description: By default, `name` and `email` values in the response, including nested
+ ones such as social profile names, are HTML-escaped (for example, `&` is returned
+ as `&`). Custom attributes and tags are never escaped. Pass `false` to return
+ them unescaped.
+ required: false
+ schema:
+ type: boolean
+ default: true
tags:
- Contacts
operationId: ShowContact
@@ -9657,6 +9918,8 @@ paths:
The `Link` header contains the path to the final merge target, resolving multi-hop merge chains (up to 3 hops).
{% /admonition %}
+
+ Requires the `read_single_user`, `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -9671,6 +9934,7 @@ paths:
external_id: '70'
role: user
email: joe@bloggs.com
+ email_domain: bloggs.com
email_verified: false
phone:
name: Joe Bloggs
@@ -9751,6 +10015,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
allOf:
@@ -9773,6 +10039,27 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 4beb09b4-d430-59c9-ad44-0708cfbc1825
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 6f4e8d0a-2b5c-4e7f-9a9d-1c0b2f3e4d5a
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
'410':
@@ -9813,7 +10100,10 @@ paths:
tags:
- Contacts
operationId: DeleteContact
- description: You can delete a single contact.
+ description: |
+ You can delete a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -9833,6 +10123,27 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 4631d568-2a95-5889-81c9-f779723578c9
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 8b6a0f2c-4d7e-4a9b-9c1f-3e2d4b5a6f7c
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
"/contacts/merge":
@@ -9846,7 +10157,7 @@ paths:
- name: include_merge_history
in: query
description: Pass `true` to include the merge history of the resulting contact
- in the response. Only returned for contacts with a `user` role.
+ in the response, with at most the 10 most recent merges.
required: false
schema:
type: boolean
@@ -9859,12 +10170,14 @@ paths:
{% admonition type="warning" name="Merged contacts are not retrievable via the API" %}
Once a merge is completed, the source contact (`from`) is permanently removed from the active contact list. This means:
- - **GET /contacts/{id}** — Requesting the source contact by its original ID will return a `404 Not Found` error.
+ - **GET /contacts/{id}** — Requesting the source contact by its original ID returns `410 Gone` with a `Link` header pointing to the contact it was merged into. See [Get a contact](/docs/references/rest-api/api.intercom.io/contacts/showcontact).
- **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 %}
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -9879,6 +10192,7 @@ paths:
external_id: '70'
role: user
email: joe@bloggs.com
+ email_domain: bloggs.com
email_verified: false
phone:
name: Joe Bloggs
@@ -9959,6 +10273,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
allOf:
@@ -9996,6 +10312,42 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 3a3f8861-b1ec-52f1-856e-b1b9bb28275c
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 9c7b1a3d-5e8f-4b0c-8d2a-4f3e5c6b7a8d
+ errors:
+ - code: not_found
+ message: User Not Found
+ schema:
+ "$ref": "#/components/schemas/error"
+ '409':
+ description: Merge in progress
+ content:
+ application/json:
+ examples:
+ Merge in progress:
+ value:
+ type: error.list
+ request_id: 0d8c2b4e-6f9a-4c1d-9e3b-5a4f6d7c8b9e
+ errors:
+ - code: merge_in_progress
+ message: Merge already in progress for one of these contacts.
+ Please retry shortly.
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -10044,7 +10396,7 @@ paths:
| --- | --- |
| `source_same_as_target` | The source contact (`from`) and the destination contact (`into`) are the same contact. A contact can't be merged into itself. |
| `invalid_merge_role_pair` | The `from`/`into` roles aren't mergeable. `into` must be a user. |
- | `no_shared_identifier` | The contacts share no email or phone. Set `skip_duplicate_validation` to preview anyway. |
+ | `no_shared_identifier` | The contacts share no email or phone. The source's phone also counts as shared when it matches the destination's WhatsApp number. Set `skip_duplicate_validation` to preview anyway. |
| `facebook_user` | Facebook contacts can't be merged. |
| `external_lead_channel_not_allowed` | The source is an external-channel lead that isn't eligible for merging. |
| `mailing_list` | Contacts created from a mailing list can't be merged. |
@@ -10052,6 +10404,8 @@ paths:
| `telegram_data_cannot_be_merged` | The Telegram sender on the source contact can't be reassigned to the destination. |
| `ms_teams_data_cannot_be_merged` | The destination contact already has a Microsoft Teams sender for the same team as the source contact, so the source's sender can't be reassigned to it. |
| `phone_data_cannot_be_merged` | The phone data on the source contact can't be reassigned to the destination. |
+
+ Requires the `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10106,7 +10460,7 @@ paths:
allowed: false
reasons:
- code: no_shared_identifier
- message: These contacts don't share a common identifier (email or phone), so they aren't recognised as duplicates. Set skip_duplicate_validation to true to preview the merge anyway.
+ message: These contacts don't share a common identifier (email, phone, or external ID), so they aren't recognised as duplicates. Set skip_duplicate_validation to true to preview the merge anyway.
schema:
"$ref": "#/components/schemas/merge_preview_response"
'401':
@@ -10121,6 +10475,27 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 5216a8fb-f031-5110-b19d-30868b50e550
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 1e9d3c5f-7a0b-4d2e-8f4c-6b5a7e8d9c0f
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -10144,12 +10519,23 @@ paths:
"$ref": "#/components/schemas/intercom_version"
- name: include_merge_history
in: query
- description: Pass `true` to include a `merge_history` array on each contact
- in the response. Only returned for contacts with a `user` role.
+ description: Pass `true` in the query string to include a `merge_history` array
+ on each contact in the response; a JSON boolean in the request body is ignored.
+ Returned for contacts of any role, with at most the 10 most recent merges.
required: false
schema:
type: boolean
default: false
+ - name: escape_identity
+ in: query
+ description: By default, `name` and `email` values in the response, including nested
+ ones such as social profile names, are HTML-escaped (for example, `&` is returned
+ as `&`). Custom attributes and tags are never escaped. Pass `false` to return
+ them unescaped.
+ required: false
+ schema:
+ type: boolean
+ default: true
tags:
- Contacts
operationId: SearchContacts
@@ -10180,6 +10566,8 @@ paths:
There are some limitations to the amount of multiple's there can be:
* There's a limit of max 2 nested filters
* There's a limit of max 15 filters for each AND or OR group
+ * There's a limit of max 15 values in an `IN` or `NIN` array
+ * `pagination.per_page` must be between 1 and 150
### Searching for Timestamp Fields
@@ -10200,10 +10588,10 @@ paths:
| Field | Type |
| ---------------------------------- | ------------------------------ |
| id | String |
- | role | String
Accepts user or lead |
+ | role | String
Accepts user or lead; contact is treated as lead |
| name | String |
| avatar | String |
- | owner_id | String |
+ | owner_id | Integer |
| email | String |
| email_domain | String |
| phone | String |
@@ -10218,6 +10606,7 @@ paths:
| last_email_clicked_at | Datetime (Unix timestamp in seconds) |
| language_override | String |
| browser | String |
+ | browser_version | String |
| browser_language | String |
| os | String |
| location.country | String |
@@ -10226,44 +10615,55 @@ paths:
| unsubscribed_from_emails | Boolean |
| marked_email_as_spam | Boolean |
| has_hard_bounced | Boolean |
+ | phone_country | String |
+ | slack_email | String |
+ | fin_qualification_status | String |
+ | whatsapp_number | String
Only on workspaces with the WhatsApp integration |
| ios_last_seen_at | Datetime (Unix timestamp in seconds) |
| ios_app_version | String |
| ios_device | String |
- | ios_app_device | String |
| ios_os_version | String |
| ios_app_name | String |
| ios_sdk_version | String |
| android_last_seen_at | Datetime (Unix timestamp in seconds) |
| android_app_version | String |
| android_device | String |
+ | android_os_version | String |
| android_app_name | String |
- | andoid_sdk_version | String |
+ | android_sdk_version | String |
+ | enabled_push_messaging | Boolean |
| segment_id | String |
| tag_id | String |
| custom_attributes.{attribute_name} | Matches the attribute's own type
(String, Integer, Float, Boolean or Date) |
+ The `ios_*` fields other than `ios_app_name` are searchable only once your workspace has been set up for the Intercom iOS SDK or has received a request from it, and the `android_*` fields other than `android_app_name` only once the same is true for the Android SDK. `enabled_push_messaging` needs either. Until then, they return an `invalid_field` error.
+
### Accepted Operators
{% admonition type="warning" name="Operators not supported on Date custom attributes" %}
- Date custom attributes do not support the `!=`, `>=`, or `<=` operators. Using them returns an error. Standard timestamp fields (`created_at`, `updated_at` etc.) do support these operators, and are filtered on the exact second.
+ Date custom attributes do not support the `!=`, `>=`, or `<=` operators. Using them returns a `422` error. Standard timestamp fields (`created_at`, `updated_at` etc.) do support these operators, and are filtered on the exact second.
{% /admonition %}
- The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). Which operators are valid depends on the field's type - see the "Valid Types" column below. Searching by `tag_id` supports only the `=` and `!=` operators.
+ The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). Which operators are valid depends on the field's type - see the "Valid Types" column below. Searching by `tag_id` or `segment_id` supports only the `=` and `!=` operators, with a single ID string as the value.
+
+ A `null` value is accepted only with `=` (matches Contacts with no value set) and `!=` (matches Contacts with any value set). An array value is accepted only with `IN` and `NIN`. String values must be shorter than 256 characters.
| Operator | Valid Types | Description |
| :------- | :---------------------------------- | :----------------------------------------------------------------------|
| = | All | Equals |
| != | All except Date | Doesn't Equal
Also matches Contacts with no value set |
- | IN | All except Date, Datetime and tag_id | In
Shortcut for `OR` queries
Values must be in Array |
- | NIN | All except Date, Datetime and tag_id | Not In
Shortcut for `OR !` queries
Values must be in Array |
- | > | Integer
Datetime
Date | Greater than
On Date custom attributes, matches from the start of the next day |
- | < | Integer
Datetime
Date | Lower than
On Date custom attributes, matches before the start of the day |
- | >= | Integer
Datetime | Greater than or equal to
Not supported on Date custom attributes |
- | <= | Integer
Datetime | Lower than or equal to
Not supported on Date custom attributes |
+ | IN | All except Date, Datetime, tag_id and segment_id | In
Shortcut for `OR` queries
Values must be in Array |
+ | NIN | All except Date, Datetime, tag_id and segment_id | Not In
Shortcut for `OR !` queries
Values must be in Array |
+ | > | Integer
Float
Datetime
Date | Greater than
On Date custom attributes, matches from the start of the next day |
+ | < | Integer
Float
Datetime
Date | Lower than
On Date custom attributes, matches before the start of the day |
+ | >= | Integer
Float
Datetime | Greater than or equal to
Not supported on Date custom attributes |
+ | <= | Integer
Float
Datetime | Lower than or equal to
Not supported on Date custom attributes |
| ~ | String | Contains |
| !~ | String | Doesn't Contain |
| ^ | String | Starts With |
| $ | String | Ends With |
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10294,6 +10694,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 648d4d57-2aa4-530b-909f-aad2c59197fe
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'400':
@@ -10308,6 +10715,63 @@ paths:
errors:
- code: invalid_sort_order
message: "Invalid sort order 'desc'. Must be one of: ascending, descending"
+ Invalid field:
+ value:
+ type: error.list
+ request_id: 3a7e2c91-5d4b-4f08-a6c3-9e1b7d2f4a60
+ errors:
+ - code: invalid_field
+ message: custom_attributes.plan_tier is not a valid search field
+ Invalid operator:
+ value:
+ type: error.list
+ request_id: 6b2f9d14-8e3a-4c57-b1d0-2a9c5e7f3b81
+ errors:
+ - code: invalid_operator
+ message: "email does not support operator: >"
+ Invalid value:
+ value:
+ type: error.list
+ request_id: 9c4a1e73-2b6d-4e98-a5f2-7d3b8c1e6a24
+ errors:
+ - code: invalid_value
+ message: Number of elements in composite query is greater than 15, please
+ try again with a smaller list
+ Invalid query:
+ value:
+ type: error.list
+ request_id: 1d8b5f26-7c3e-4a19-b2e4-5f6a9d0c8b37
+ errors:
+ - code: invalid_query
+ message: Query body must contain a query hash
+ Query nested too deeply:
+ value:
+ type: error.list
+ request_id: 4e9c2a58-1f7b-4d36-8a0e-3b5d7c9f1e42
+ errors:
+ - code: invalid_values
+ message: Value depth exceeds 2 items
+ Invalid per_page:
+ value:
+ type: error.list
+ request_id: 7f3d6b09-4a2c-4e85-9b1f-8c0e2d5a7b63
+ errors:
+ - code: invalid_per_page
+ message: per_page must be an integer between 0 and 150
+ schema:
+ "$ref": "#/components/schemas/error"
+ '422':
+ description: Unsupported operator on a Date custom attribute
+ content:
+ application/json:
+ examples:
+ Unsupported date comparison:
+ value:
+ type: error.list
+ request_id: 2c5e8a17-9d3f-4b60-a7c4-1e8f3b6d9a05
+ errors:
+ - code: data_invalid
+ message: "Date predicate doesn't support comparison type :ne"
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -10341,7 +10805,7 @@ paths:
- name: per_page
in: query
required: false
- description: The number of results to return per page. Defaults to 50, minimum 1, maximum 150.
+ description: The number of results to return per page. Defaults to 50, minimum 1, maximum 150; larger values are treated as `150`. Only the leading digits are read, so `1.5` is treated as `1`. A value that doesn't start with a positive integer, such as `0` or `abc`, returns a `400` error with code `invalid_per_page`.
schema:
type: integer
default: 50
@@ -10359,10 +10823,14 @@ paths:
description: |
You can fetch a list of contact activity events for your workspace, such as when contacts are created, role updated, merged, or deleted. Events are returned oldest first.
+ If the activity store can't be read, this endpoint returns `200` with an empty `data` array and no `pages.next`, the same response as when there are no new events.
+
{% admonition type="warning" name="Pagination" %}
You can use pagination to limit the number of results returned. The default is `50` results per page, with a maximum of `150`.
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.
{% /admonition %}
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10412,11 +10880,25 @@ paths:
created_at: 1717000400
pages:
type: pages
- per_page: 50
+ per_page: 5
next:
starting_after: '1717000400000.0000e5'
schema:
"$ref": "#/components/schemas/contact_activity_list"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Invalid per_page:
+ value:
+ type: error.list
+ request_id: 5a1c7e39-6b2d-4f84-9e0a-3c8d1f5b7a26
+ errors:
+ - code: invalid_per_page
+ message: per_page must be a positive integer
+ schema:
+ "$ref": "#/components/schemas/error"
'401':
description: Unauthorized
content:
@@ -10429,6 +10911,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 3aa05fbd-7443-55e1-9b80-7766454b008d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
"/contacts":
@@ -10442,11 +10931,42 @@ paths:
- name: include_merge_history
in: query
description: Pass `true` to include a `merge_history` array on each contact
- in the response. Only returned for contacts with a `user` role.
+ in the response. Returned for contacts of any role, with at most the 10 most
+ recent merges.
required: false
schema:
type: boolean
default: false
+ - name: escape_identity
+ in: query
+ description: By default, `name` and `email` values in the response, including nested
+ ones such as social profile names, are HTML-escaped (for example, `&` is returned
+ as `&`). Custom attributes and tags are never escaped. Pass `false` to return
+ them unescaped.
+ required: false
+ schema:
+ type: boolean
+ default: true
+ - name: per_page
+ in: query
+ description: The number of results per page. Defaults to `10`, with a maximum
+ of `150`; larger values are treated as `150`. Only the leading digits are read,
+ so `1.5` is treated as `1`. A value that doesn't start with a positive integer,
+ such as `0` or `abc`, returns a `400` error with code `invalid_per_page`.
+ required: false
+ schema:
+ type: integer
+ minimum: 1
+ default: 10
+ maximum: 150
+ - name: starting_after
+ in: query
+ description: The cursor value from `pages.next.starting_after` in a previous
+ response. An empty value is ignored. A value that isn't a valid cursor returns
+ a `400` error with code `client_error`.
+ required: false
+ schema:
+ type: string
tags:
- Contacts
operationId: ListContacts
@@ -10459,6 +10979,8 @@ paths:
You can use pagination to limit the number of results returned. The default is `10` results per page, with a maximum of `150`.
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.
{% /admonition %}
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10489,6 +11011,34 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: e3b9f9b0-51d9-5926-bca5-4f5b6c9a3e5c
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Invalid per_page:
+ value:
+ type: error.list
+ request_id: 0b6e3d82-5f1a-4c97-a2d8-6e9f4b1c3a75
+ errors:
+ - code: invalid_per_page
+ message: per_page must be a positive integer
+ Invalid starting_after:
+ value:
+ type: error.list
+ request_id: 8e2a4c61-3d7f-4b05-9c1e-5a8b2f6d0e94
+ errors:
+ - code: client_error
+ message: Invalid starting_after param. Please try again using a starting_after value from a paginated response
schema:
"$ref": "#/components/schemas/error"
post:
@@ -10501,7 +11051,10 @@ paths:
tags:
- Contacts
operationId: CreateContact
- description: You can create a new contact (ie. user or lead).
+ description: |
+ You can create a new contact (ie. user or lead).
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -10516,6 +11069,7 @@ paths:
external_id:
role: user
email: joebloggs@intercom.io
+ email_domain: intercom.io
email_verified: false
phone:
name:
@@ -10596,6 +11150,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
allOf:
@@ -10618,6 +11174,101 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: ae05b405-0bc7-5a7f-b519-0bcb15655216
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Invalid timestamp:
+ value:
+ type: error.list
+ request_id: 9d3b7f15-2c8e-4a61-b4d9-0e5f2a7c1b38
+ errors:
+ - code: parameter_invalid
+ message: "'signed_up_at' appears to be in milliseconds. Timestamps
+ must be Unix timestamps in seconds."
+ Owner not a teammate:
+ value:
+ type: error.list
+ request_id: 1e4c8a26-3d9f-4b72-a5e0-7f6a3b8d2c49
+ errors:
+ - code: parameter_invalid
+ message: The owner specified is not a member of the app
+ Custom attribute does not exist:
+ value:
+ type: error.list
+ request_id: 2f5d9b37-4e0a-4c83-b6f1-8a7b4c9e3d50
+ errors:
+ - code: parameter_invalid
+ message: Custom attribute 'plan_tier' does not exist
+ Invalid custom attributes:
+ value:
+ type: error.list
+ request_id: 3a6e0c48-5f1b-4d94-87a2-9b8c5d0f4e61
+ errors:
+ - code: nested_custom_attributes
+ message: "'custom_attributes' must be an object"
+ schema:
+ "$ref": "#/components/schemas/error"
+ '409':
+ description: Contact already exists
+ content:
+ application/json:
+ examples:
+ Contact already exists:
+ value:
+ type: error.list
+ request_id: 4b7f1d59-6a2c-4ea5-98b3-0c9d6e1a5f72
+ errors:
+ - code: conflict
+ message: A contact matching those details already exists with
+ id=6762f0dd1bb69f9f2193bb83
+ Archived contact already exists:
+ value:
+ type: error.list
+ request_id: 5c8a2e6a-7b3d-4fb6-89c4-1d0e7f2b6a83
+ errors:
+ - code: conflict
+ message: An archived contact matching those details already
+ exists with id=6762f0dd1bb69f9f2193bb83
+ Multiple matching contacts:
+ value:
+ type: error.list
+ request_id: 2d7b9e41-6c3a-4f08-b5d2-9a1e7c4f0b63
+ errors:
+ - code: conflict
+ message: Multiple contacts matching those details already exists
+ with id= email=joe@example.com
+ Contact created at the same time:
+ value:
+ type: error.list
+ request_id: 6f1a3c8e-9d2b-4a75-8e40-b3c6d1f9a082
+ errors:
+ - code: conflict
+ message: A contact matching those details already exists
+ schema:
+ "$ref": "#/components/schemas/error"
+ '422':
+ description: Unprocessable Entity
+ content:
+ application/json:
+ examples:
+ Invalid email:
+ value:
+ type: error.list
+ request_id: 6d9b3f7b-8c4e-4ac7-9ad5-2e1f8a3c7b94
+ errors:
+ - code: parameter_invalid
+ message: "'email' is not a valid email address."
schema:
"$ref": "#/components/schemas/error"
requestBody:
@@ -10649,11 +11300,21 @@ paths:
- name: include_merge_history
in: query
description: Pass `true` to include the contact's merge history in the response.
- Only returned for contacts with a `user` role.
+ Returned for contacts of any role, with at most the 10 most recent merges.
required: false
schema:
type: boolean
default: false
+ - name: escape_identity
+ in: query
+ description: By default, `name` and `email` values in the response, including nested
+ ones such as social profile names, are HTML-escaped (for example, `&` is returned
+ as `&`). Custom attributes and tags are never escaped. Pass `false` to return
+ them unescaped.
+ required: false
+ schema:
+ type: boolean
+ default: true
tags:
- Contacts
operationId: ShowContactByExternalId
@@ -10663,6 +11324,8 @@ paths:
{% admonition type="info" name="Merged contacts return 410 Gone" %}
If the contact with this external ID has been merged into another contact, the API returns **HTTP 410 Gone** with a `Link` header pointing to the canonical (merged-into) contact. See `GET /contacts/{id}` for details on the response format.
{% /admonition %}
+
+ Requires the `read_single_user`, `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -10677,6 +11340,7 @@ paths:
external_id: '70'
role: user
email: joe@bloggs.com
+ email_domain: bloggs.com
email_verified: false
phone:
name: Joe Bloggs
@@ -10757,6 +11421,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
allOf:
@@ -10779,6 +11445,27 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: c3ae8c73-bd9a-5a00-b68c-fc7c932d59a8
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 7a5f9e1b-3c6d-4f8a-8b0e-2d1c3a4f5e6b
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
'410':
@@ -10821,7 +11508,10 @@ paths:
tags:
- Contacts
operationId: ArchiveContact
- description: You can archive a single contact.
+ description: |
+ You can archive a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -10829,6 +11519,22 @@ paths:
application/json:
schema:
"$ref": "#/components/schemas/contact_archived"
+ '401':
+ "$ref": "#/components/responses/Unauthorized"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 8d6c0b2e-4f7a-4c9d-9e1b-3a2f4d5c6b7e
+ errors:
+ - code: not_found
+ message: User Not Found
+ schema:
+ "$ref": "#/components/schemas/error"
"/contacts/{contact_id}/unarchive":
post:
summary: Unarchive contact
@@ -10847,7 +11553,10 @@ paths:
tags:
- Contacts
operationId: UnarchiveContact
- description: You can unarchive a single contact.
+ description: |
+ You can unarchive a single contact.
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
responses:
'200':
description: successful
@@ -10855,6 +11564,60 @@ paths:
application/json:
schema:
"$ref": "#/components/schemas/contact_unarchived"
+ '400':
+ description: Contact can't be restored
+ content:
+ application/json:
+ examples:
+ Blocked contact:
+ value:
+ type: error.list
+ request_id: 9e7d1c3f-5a8b-4d0e-8f2c-4b3a5e6d7c8f
+ errors:
+ - code: not_restorable
+ message: User has been blocked and is not restorable. See your
+ App blocked user list for more detail.
+ Merged contact:
+ value:
+ type: error.list
+ request_id: 0f8e2d4a-6b9c-4e1f-9a3d-5c4b6f7e8d9a
+ errors:
+ - code: bad_request
+ message: User has been merged and is not restorable.
+ Pending permanent deletion:
+ value:
+ type: error.list
+ request_id: 1a9f3e5b-7c0d-4f2a-8b4e-6d5c7a8f9e0b
+ errors:
+ - code: bad_request
+ message: User has been marked for permanent deletion and is not
+ restorable.
+ Duplicate contact:
+ value:
+ type: error.list
+ request_id: 2b0a4f6c-8d1e-4a3b-9c5f-7e6d8b9a0f1c
+ errors:
+ - code: unique_user_constraint
+ message: This user is archived but cannot be restored because
+ another user exists with this email or user_id.
+ schema:
+ "$ref": "#/components/schemas/error"
+ '401':
+ "$ref": "#/components/responses/Unauthorized"
+ '404':
+ description: Contact not found
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 3c1b5a7d-9e2f-4b4c-8d6a-8f7e9c0b1a2d
+ errors:
+ - code: not_found
+ message: User Not Found
+ schema:
+ "$ref": "#/components/schemas/error"
"/contacts/{id}/banners":
get:
summary: List banners for a contact
@@ -10881,6 +11644,8 @@ paths:
with the dismiss endpoint. A returned banner is treated as shown: requesting
this endpoint records an impression for each banner returned, so call it at the
point you are about to display the banners, not speculatively.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: Successful response
@@ -10904,6 +11669,8 @@ paths:
created_at: 1780580493
schema:
"$ref": "#/components/schemas/banner_list"
+ '401':
+ "$ref": "#/components/responses/Unauthorized"
'404':
description: Contact not found
content:
@@ -10949,6 +11716,8 @@ paths:
The request is idempotent: dismissing an already-dismissed banner succeeds and
returns the same response.
+
+ Requires the `read_write_users` OAuth scope.
responses:
'200':
description: Successful response
@@ -10962,8 +11731,10 @@ paths:
dismissed: true
schema:
"$ref": "#/components/schemas/banner_dismiss"
+ '401':
+ "$ref": "#/components/responses/Unauthorized"
'404':
- description: Banner view not found
+ description: Banner view or contact not found
content:
application/json:
examples:
@@ -10974,6 +11745,13 @@ paths:
errors:
- code: not_found
message: Resource Not Found
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 8a2d6f0e-4b7c-4e19-9f3a-1c5e8b2d7f46
+ errors:
+ - code: not_found
+ message: User Not Found
schema:
"$ref": "#/components/schemas/error"
"/contacts/{contact_id}/block":
@@ -10994,7 +11772,10 @@ paths:
tags:
- Contacts
operationId: BlockContact
- description: Block a single contact.
**Note:** conversations of the contact will also be archived during the process.
More details in [FAQ How do I block Inbox spam?](https://www.intercom.com/help/en/articles/8838656-inbox-faqs)
+ description: |
+ Block a single contact.
**Note:** conversations of the contact will also be archived during the process.
More details in [FAQ How do I block Inbox spam?](https://www.intercom.com/help/en/articles/8838656-inbox-faqs)
+
+ Requires the `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -11002,6 +11783,29 @@ paths:
application/json:
schema:
"$ref": "#/components/schemas/contact_blocked"
+ '400':
+ description: Bad Request
+ content:
+ application/json:
+ examples:
+ Contact not found:
+ value:
+ type: error.list
+ request_id: 4d2c6b8e-0f3a-4c5d-9e7b-9a8f0d1c2b3e
+ errors:
+ - code: parameter_invalid
+ message: The user 63a07ddf05a32042dffac965 could not be found
+ Company email address:
+ value:
+ type: error.list
+ request_id: 5e3d7c9f-1a4b-4d6e-8f8c-0b9a1e2d3c4f
+ errors:
+ - code: parameter_invalid
+ message: The user 63a07ddf05a32042dffac965 has a company email address
+ schema:
+ "$ref": "#/components/schemas/error"
+ '401':
+ "$ref": "#/components/responses/Unauthorized"
"/contacts/{id}/merge_histories":
get:
summary: Get contact merge history
@@ -11026,7 +11830,8 @@ paths:
type: string
- name: per_page
in: query
- description: The number of results to return per page (default 50, max 150).
+ description: The number of results to return per page (default 50, max 150). A value
+ outside 1–150 returns a `422` error.
required: false
schema:
type: integer
@@ -11035,7 +11840,8 @@ paths:
maximum: 150
- name: order
in: query
- description: The order to return results in. Defaults to descending.
+ description: The order to return results in. Defaults to descending. Any other value
+ returns a `422` error.
required: false
schema:
type: string
@@ -11049,6 +11855,8 @@ paths:
Retrieve the paginated list of contacts that have been merged into a given contact.
Only available for contacts with a `user` role. Returns a `404` if the contact is not found or has a `lead` role.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -11079,6 +11887,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 69c5df7c-0c2b-5596-90f6-b3b636ea51c8
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'404':
@@ -11092,7 +11907,34 @@ paths:
request_id: 45b30bd1-75d2-40cc-bb39-74ac133a2836
errors:
- code: not_found
- message: Contact not found
+ message: User Not Found
+ Contact is not a user:
+ value:
+ type: error.list
+ errors:
+ - code: not_found
+ message: Not Found
+ schema:
+ "$ref": "#/components/schemas/error"
+ '422':
+ description: Invalid parameter
+ content:
+ application/json:
+ examples:
+ Invalid per_page:
+ value:
+ type: error.list
+ request_id:
+ errors:
+ - code: parameter_invalid
+ message: Limit is too big
+ Invalid cursor:
+ value:
+ type: error.list
+ request_id:
+ errors:
+ - code: parameter_invalid
+ message: must be a valid base64-encoded JSON cursor
schema:
"$ref": "#/components/schemas/error"
"/contacts/bulk":
@@ -11124,6 +11966,8 @@ paths:
- You can append tasks to an existing job by including `job.id` in the request body.
- Tag application is best-effort and processed asynchronously: unknown tag IDs are skipped, and per-tag results are not returned in the job status.
{% /admonition %}
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
requestBody:
content:
application/json:
@@ -11218,6 +12062,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 941c4b1b-d76e-5cd5-a1bb-6d69ad1905ed
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'403':
@@ -11305,6 +12156,8 @@ paths:
- You can append tasks to an existing job by including `job.id` in the request body.
- Tag application is best-effort and processed asynchronously: unknown tag IDs are skipped, and per-tag results are not returned in the job status.
{% /admonition %}
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
requestBody:
content:
application/json:
@@ -11399,6 +12252,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: 1a6d2e20-cdad-5c98-a063-26454d9eb71d
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'403':
@@ -11495,6 +12355,8 @@ paths:
- Maximum of 100 contacts per request.
- You can append tasks to an existing job by including `job.id` in the request body.
{% /admonition %}
+
+ Requires the `read_write_users` or `write_users_companies` OAuth scope.
requestBody:
content:
application/json:
@@ -11550,6 +12412,13 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: a4abbb6a-8868-585e-be5b-b068a3dd5fd0
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
schema:
"$ref": "#/components/schemas/error"
'403':
@@ -11641,7 +12510,9 @@ paths:
- Contacts
operationId: ShowBulkUpdateContactsJob
description: |
- You can check the status of a bulk contact update job. The `state` field indicates the overall job progress: `pending`, `running`, `completed`, or `completed_with_errors`.
+ You can check the status of a bulk contact update job. The `state` field indicates the overall job progress: `running`, `completed`, or `completed_with_errors`.
+
+ Requires the `read_users_companies` or `read_write_users` OAuth scope.
responses:
'200':
description: successful
@@ -11678,6 +12549,27 @@ paths:
errors:
- code: unauthorized
message: Access Token Invalid
+ Token lacks required scope:
+ value:
+ type: error.list
+ request_id: e4462db2-6098-589c-b6b4-3f6c6e8f2250
+ errors:
+ - code: token_unauthorized
+ message: Not authorized to access resource
+ schema:
+ "$ref": "#/components/schemas/error"
+ '404':
+ description: Job not found
+ content:
+ application/json:
+ examples:
+ Job not found:
+ value:
+ type: error.list
+ request_id: 7e0c4a8d-9d5f-4bd8-8be6-3f2a9b4d8c05
+ errors:
+ - code: not_found
+ message: Resource Not Found
schema:
"$ref": "#/components/schemas/error"
"/content/bulk_actions":
@@ -24999,6 +25891,7 @@ paths:
external_id:
role: user
email: foo@bar.com
+ email_domain: bar.com
email_verified: false
phone:
name:
@@ -25079,6 +25972,8 @@ paths:
utm_source:
utm_term:
referrer:
+ sms_consent: false
+ unsubscribed_from_sms: false
enabled_push_messaging:
schema:
"$ref": "#/components/schemas/contact"
@@ -29114,7 +30009,7 @@ components:
email_verified:
type: boolean
description: >-
- Whether the contact has proved they own their current email address. `true` only when this address was marked verified through the Contacts API (`email_verified: true` on create or update) and has not changed since; it becomes `false` again if the contact's email changes, until the new address is verified. Intercom reuses a lead with a verified email when it later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead.
+ Whether the contact has proved they own their current email address. `true` only when this address was marked verified through the Contacts API (`email_verified: true` on create or update) and has not changed since; it becomes `false` again if the contact's email changes, until the new address is verified. Intercom reuses a lead with a verified email when it later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. In List contacts and Search contacts responses it is left out only if the contact can't be loaded, for example when it is deleted while the request runs.
example: true
phone:
type: string
@@ -29287,19 +30182,11 @@ components:
type: object
description: The custom attributes which are set for the contact.
avatar:
- type: object
+ type: string
+ format: uri
nullable: true
- properties:
- type:
- type: string
- description: The type of object
- example: avatar
- image_url:
- type: string
- format: uri
- nullable: true
- description: An image URL containing the avatar of a contact.
- example: https://example.org/128Wash.jpg
+ description: An image URL containing the avatar of a contact.
+ example: https://example.org/128Wash.jpg
tags:
"$ref": "#/components/schemas/contact_tags"
notes:
@@ -29310,12 +30197,59 @@ components:
"$ref": "#/components/schemas/contact_location"
social_profiles:
"$ref": "#/components/schemas/contact_social_profiles"
+ opted_out_subscription_types:
+ "$ref": "#/components/schemas/contact_subscription_types"
+ opted_in_subscription_types:
+ "$ref": "#/components/schemas/contact_subscription_types"
+ utm_campaign:
+ type: string
+ nullable: true
+ description: The `utm_campaign` value recorded for the contact.
+ example: spring_launch
+ utm_content:
+ type: string
+ nullable: true
+ description: The `utm_content` value recorded for the contact.
+ example: banner_ad
+ utm_medium:
+ type: string
+ nullable: true
+ description: The `utm_medium` value recorded for the contact.
+ example: email
+ utm_source:
+ type: string
+ nullable: true
+ description: The `utm_source` value recorded for the contact.
+ example: newsletter
+ utm_term:
+ type: string
+ nullable: true
+ description: The `utm_term` value recorded for the contact.
+ example: support_software
+ referrer:
+ type: string
+ nullable: true
+ description: The URL of the page the contact came from, as recorded by the Messenger.
+ example: https://example.com/pricing
+ sms_consent:
+ type: boolean
+ description: Whether the contact has consented to receive SMS messages.
+ example: false
+ unsubscribed_from_sms:
+ type: boolean
+ description: Whether the contact is unsubscribed from SMS messages.
+ example: false
+ enabled_push_messaging:
+ type: boolean
+ nullable: true
+ description: Whether the contact has a mobile device registered to receive push messages.
+ example: true
merge_history:
type: array
nullable: true
- description: A list of contacts that were merged into this contact. Only
- included in the response when `include_merge_history=true` is passed as
- a query parameter. Only available for contacts with a `user` role.
+ description: A list of contacts that were merged into this contact, most
+ recent first, capped at 10. Only included in the response when
+ `include_merge_history=true` is passed as a query parameter.
items:
"$ref": "#/components/schemas/merge_history_item"
contact_attached_companies:
@@ -29329,7 +30263,7 @@ components:
enum:
- list
example: list
- companies:
+ data:
type: array
description: An array containing Company Objects
items:
@@ -29427,28 +30361,23 @@ components:
example: 6329bd9ffe4e2e91dc5d6a1e
external_id:
type: string
- nullable: true
- description: The external identifier of the contact, if one is set.
+ description: The external identifier of the contact. Omitted when not set.
example: user-42
role:
type: string
- nullable: true
- description: The role of the contact at the time of the event, either user, lead, or visitor.
+ description: The role of the contact at the time of the event, either user, lead, or visitor. Omitted when not recorded.
example: user
merge_source_id:
type: string
- nullable: true
- description: For merge events, the identifier of the contact that was merged away.
+ description: For merge events, the identifier of the contact that was merged away. Omitted on other events.
example: 5f7f0d217c3f2e001a4e8b12
merge_target_id:
type: string
- nullable: true
- description: For merge events, the identifier of the contact that was merged into.
+ description: For merge events, the identifier of the contact that was merged into. Omitted on other events.
example: 6329bd9ffe4e2e91dc5d6a1e
failure_reason:
type: string
- nullable: true
- description: For failed events, the reason the activity did not succeed.
+ description: For failed events, the reason the activity did not succeed. Omitted on other events.
example: duplicate_external_id
created_at:
type: integer
@@ -29486,8 +30415,7 @@ components:
example: 10
next:
type: object
- nullable: true
- description: Cursor for the next page of results.
+ description: Cursor for the next page of results. Omitted on the last page.
properties:
starting_after:
type: string
@@ -29537,7 +30465,6 @@ components:
type: string
description: The current state of the job.
enum:
- - pending
- running
- completed
- completed_with_errors
@@ -29556,8 +30483,9 @@ components:
type: integer
format: date-time
nullable: true
- description: The time the job completed as a Unix timestamp. Null if not
- yet completed.
+ description: The time the most recent task completed as a Unix timestamp.
+ Set as soon as any task completes, so check `state` to know whether
+ the whole job has finished. Null until a task completes.
example: 1713360120
tasks:
type: array
@@ -29631,6 +30559,16 @@ components:
nullable: true
description: The city that the contact is located in
example: Dublin
+ country_code:
+ type: string
+ nullable: true
+ description: The ISO 3166-1 alpha-3 code of the country that the contact is located in
+ example: IRL
+ continent_code:
+ type: string
+ nullable: true
+ description: The code of the continent that the contact is located in
+ example: EU
contact_notes:
title: Contact notes
type: object
@@ -29905,6 +30843,12 @@ components:
description: An object containing Subscription Types meta data about the SubscriptionTypes
that a contact has.
properties:
+ type:
+ type: string
+ description: The type of the object
+ enum:
+ - list
+ example: list
data:
type: array
description: This object represents the subscriptions attached to a contact.
@@ -32687,7 +33631,7 @@ components:
properties:
role:
type: string
- description: The role of the contact.
+ description: The role of the contact. `lead` creates a lead; any other value creates a user.
example: user
external_id:
type: string
@@ -32744,6 +33688,20 @@ components:
nullable: true
description: Whether the contact is unsubscribed from emails
example: true
+ sms_consent:
+ type: boolean
+ description: Whether the contact has consented to receive SMS messages.
+ example: false
+ unsubscribed_from_sms:
+ type: boolean
+ description: Whether the contact is unsubscribed from SMS messages.
+ example: false
+ language_override:
+ type: string
+ nullable: true
+ description: A preferred language setting for the contact, used by the Intercom
+ Messenger even if their browser settings change.
+ example: en
custom_attributes:
type: object
nullable: true
@@ -37962,7 +38920,7 @@ components:
type: string
nullable: true
description: A cursor to pass as the `cursor` query parameter to fetch
- the next page of results. Absent when there are no more pages.
+ the next page of results. `null` when there are no more pages.
example: WyIxNjM0NTY3ODkwIl0
has_more:
type: boolean
@@ -38064,7 +39022,7 @@ components:
properties:
attributes:
type: array
- description: The individual attribute changes. Capped at 50 items; total_count reflects the full number of changes.
+ description: The individual attribute changes. At most 50 custom attribute changes are included; changes to standard fields are always included, so this array can hold more than 50 items. total_count reflects the full number of changes.
items:
"$ref": "#/components/schemas/merge_preview_attribute_change"
total_count:
@@ -40605,7 +41563,8 @@ components:
properties:
role:
type: string
- description: The role of the contact.
+ description: The role of the contact, either `user` or `lead`. Any other value is ignored.
+ A user can't be changed to a lead; sending `lead` for a user returns a `400` error.
external_id:
type: string
description: A unique identifier for the contact which is given to Intercom
@@ -40660,6 +41619,20 @@ components:
nullable: true
description: Whether the contact is unsubscribed from emails
example: true
+ sms_consent:
+ type: boolean
+ description: Whether the contact has consented to receive SMS messages.
+ example: false
+ unsubscribed_from_sms:
+ type: boolean
+ description: Whether the contact is unsubscribed from SMS messages.
+ example: false
+ language_override:
+ type: string
+ nullable: true
+ description: A preferred language setting for the contact, used by the Intercom
+ Messenger even if their browser settings change.
+ example: en
custom_attributes:
type: object
nullable: true