The intercom API reference.
URL https://developers.intercom.com
License MIT
The intercom API reference.
With the AI Content APIs, you can create and manage External Pages and Content Import Sources for your Fin Content Library.
Â
External Pages are pages that you want Fin to be able to answer questions about. The API for External Pages is a great way to ingest into your Fin Content Library pages that are not publicly accessible and hence can't be crawled by Intercom.
Â
Content Import Sources are the sources of those pages, and they are used to determine the default audience for the pages (configured via the UI). You should create a Content Import Source for each source of External Pages that you want to ingest into your Fin Content Library.
Â
You can then iterate through the content from that source via its API and POST it to the External Pages endpoint. That endpoint has an external_id parameter which allows you to specify the identifier from the source. The endpoint will then either create a new External Page or update an existing one as appropriate.",
Contact are the objects that represent your leads and users in Intercom.
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
The contacts phone number normalized to the E164 format
The id of an admin that has been assigned account ownership of the contact.
Whether the contact has marked an email sent to them as spam.
(UNIX timestamp) The time when the contact was created.
(UNIX timestamp) The time when the contact was last updated.
(UNIX timestamp) The time specified for when a contact signed up.
(UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
(UNIX timestamp) The time when the contact last messaged in.
(UNIX timestamp) The time when the contact was last messaged.
(UNIX timestamp) The time when the contact last opened an email.
(UNIX timestamp) The time when the contact last clicked a link in an email.
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
The version of the browser which the contact is using.
The language set by the browser which the contact is using.
The name of the Android app which the contact is using.
The version of the Android app which the contact is using.
The version of the Android OS which the contact is using.
The version of the Android SDK which the contact is using.
(UNIX timestamp) The time when the contact was last seen on an Android device.
The version of the iOS app which the contact is using.
The version of the iOS SDK which the contact is using.
(UNIX timestamp) The last time the contact used the iOS app.
An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.
{ "type": "contact", "id": "5ba682d23d7cf92bef87bfd4", "external_id": "f3b87a2e09d514c6c2e79b9a", "workspace_id": "ecahpwf5", "role": "user", "email": "joe@example.com", "email_domain": "example.com", "phone": "+1123456789", "formatted_phone": "+1123456789", "name": "John Doe", "owner_id": 123, "has_hard_bounced": true, "marked_email_as_spam": true, "unsubscribed_from_emails": true, "created_at": 1571672154, "updated_at": 1571672154, "signed_up_at": 1571672154, "last_seen_at": 1571672154, "last_replied_at": 1571672154, "last_contacted_at": 1571672154, "last_email_opened_at": 1571672154, "last_email_clicked_at": 1571672154, "language_override": "en", "browser": "Chrome", "browser_version": "80.0.3987.132", "browser_language": "en-US", "os": "Mac OS X", "android_app_name": "Intercom", "android_app_version": "5.0.0", "android_device": "Pixel 3", "android_os_version": "10", "android_sdk_version": "28", "android_last_seen_at": 1571672154, "ios_app_name": "Intercom", "ios_app_version": "5.0.0", "ios_device": "iPhone 11", "ios_os_version": "13.3.1", "ios_sdk_version": "13.3.1", "ios_last_seen_at": 1571672154, "custom_attributes": {}, "avatar": { "type": "avatar", "image_url": "https://example.org/128Wash.jpg" }, "tags": { "data": [ … ], "url": "/contacts/5ba682d23d7cf92bef87bfd4/tags", "total_count": 100, "has_more": true }, "notes": { "data": [ … ], "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes", "total_count": 100, "has_more": true }, "companies": { "url": "/contacts/5ba682d23d7cf92bef87bfd4/companies", "total_count": 100, "has_more": true }, "location": { "type": "location", "country": "Ireland", "region": "Dublin", "city": "Dublin" }, "social_profiles": { "data": [ … ] } }
curl -i -X GET \ 'https://api.intercom.io/companies/{id}/contacts' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "type": "list", "data": [], "total_count": 0, "pages": { "type": "pages", "page": 1, "per_page": 50, "total_pages": 0 } }
curl -i -X POST \ 'https://api.intercom.io/contacts/{id}/companies' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "id": "66fd00f69ffbe52cc8b3aa16" }'
{ "type": "company", "company_id": "1", "id": "66fd00f69ffbe52cc8b3aa16", "app_id": "this_is_an_id197_that_should_be_at_least_", "name": "company6", "remote_created_at": 1727856886, "created_at": 1727856886, "updated_at": 1727856886, "monthly_spend": 0, "session_count": 0, "user_count": 1, "tags": { "type": "tag.list", "tags": [] }, "segments": { "type": "segment.list", "segments": [] }, "plan": {}, "custom_attributes": {} }
curl -i -X GET \ 'https://api.intercom.io/contacts/{id}/companies' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
successful
The majority of list resources in the API are paginated to allow clients to traverse data over multiple requests.
Their responses are likely to contain a pages object that hosts pagination links which a client can use to paginate through the data without having to construct a query. The link relations for the pages field are as follows.
{ "type": "list", "data": [ { … } ], "pages": { "type": "pages", "next": null, "page": 1, "per_page": 50, "total_pages": 1 }, "total_count": 1 }
curl -i -X DELETE \ 'https://api.intercom.io/contacts/{contact_id}/companies/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "type": "company", "company_id": "1", "id": "66fd00fb9ffbe52cc8b3aa26", "app_id": "this_is_an_id205_that_should_be_at_least_", "name": "company8", "remote_created_at": 1727856891, "created_at": 1727856891, "updated_at": 1727856892, "monthly_spend": 0, "session_count": 0, "user_count": 0, "tags": { "type": "tag.list", "tags": [] }, "segments": { "type": "segment.list", "segments": [] }, "plan": {}, "custom_attributes": {} }
curl -i -X GET \ 'https://api.intercom.io/contacts/{id}/notes' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
Successful response
Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.
{ "type": "list", "data": [ { … }, { … }, { … } ], "total_count": 3, "pages": { "type": "pages", "next": null, "page": 1, "per_page": 50, "total_pages": 1 } }
curl -i -X POST \ 'https://api.intercom.io/contacts/{id}/notes' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "contact_id": "66fd01069ffbe52cc8b3aa44", "admin_id": 991266954, "body": "Hello" }'
{ "type": "note", "id": "21", "created_at": 1727856903, "contact": { "type": "contact", "id": "66fd01069ffbe52cc8b3aa44" }, "author": { "type": "admin", "id": "991266954", "name": "Ciaran124 Lee", "email": "admin124@email.com", "away_mode_enabled": false, "away_mode_reassign": false }, "body": "<p>Hello</p>" }
curl -i -X GET \ 'https://api.intercom.io/contacts/{contact_id}/segments' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "type": "list", "data": [ { … } ] }
You can fetch a list of subscription types that are attached to a contact. These can be subscriptions that a user has 'opted-in' to or has 'opted-out' from, depending on the subscription type. This will return a list of Subscription Type objects that the contact is associated with.
The data property will show a combined list of:
1.Opt-out subscription types that the user has opted-out from. 2.Opt-in subscription types that the user has opted-in to receiving.
curl -i -X GET \ 'https://api.intercom.io/contacts/{contact_id}/subscriptions' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "type": "list", "data": [ { … }, { … } ] }
You can add a specific subscription to a contact. In Intercom, we have two different subscription types based on user consent - opt-out and opt-in:
1.Attaching a contact to an opt-out subscription type will opt that user out from receiving messages related to that subscription type.
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.
The unique identifier for the subscription which is given by Intercom
curl -i -X POST \ 'https://api.intercom.io/contacts/{contact_id}/subscriptions' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "id": 62, "consent_type": "opt_in" }'
{ "type": "subscription", "id": "62", "state": "live", "consent_type": "opt_in", "default_translation": { "name": "Newsletters", "description": "Lorem ipsum dolor sit amet", "locale": "en" }, "translations": [ { … } ], "content_types": [ "sms_message" ] }
curl -i -X DELETE \ 'https://api.intercom.io/contacts/{contact_id}/subscriptions/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "type": "subscription", "id": "78", "state": "live", "consent_type": "opt_in", "default_translation": { "name": "Newsletters", "description": "Lorem ipsum dolor sit amet", "locale": "en" }, "translations": [ { … } ], "content_types": [ "sms_message" ] }
curl -i -X POST \ 'https://api.intercom.io/contacts/{contact_id}/tags' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "id": 48 }'
{ "type": "tag", "id": "48", "name": "Manual tag" }
curl -i -X DELETE \ 'https://api.intercom.io/contacts/{contact_id}/tags/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "type": "tag", "id": "51", "name": "Manual tag" }
You can update a contact
An image URL containing the avatar of a contact
The time specified for when a contact signed up
The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually)
The id of an admin that has been assigned account ownership of the contact
Whether the contact is unsubscribed from emails
curl -i -X PUT \ 'https://api.intercom.io/contacts/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "email": "joebloggs@intercom.io", "name": "joe bloggs" }'
successful
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
The contacts phone number normalized to the E164 format
The id of an admin that has been assigned account ownership of the contact.
Whether the contact has marked an email sent to them as spam.
(UNIX timestamp) The time when the contact was created.
(UNIX timestamp) The time when the contact was last updated.
(UNIX timestamp) The time specified for when a contact signed up.
(UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
(UNIX timestamp) The time when the contact last messaged in.
(UNIX timestamp) The time when the contact was last messaged.
(UNIX timestamp) The time when the contact last opened an email.
(UNIX timestamp) The time when the contact last clicked a link in an email.
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
The version of the browser which the contact is using.
The language set by the browser which the contact is using.
The name of the Android app which the contact is using.
The version of the Android app which the contact is using.
The version of the Android OS which the contact is using.
The version of the Android SDK which the contact is using.
(UNIX timestamp) The time when the contact was last seen on an Android device.
The version of the iOS app which the contact is using.
The version of the iOS SDK which the contact is using.
(UNIX timestamp) The last time the contact used the iOS app.
An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.
{ "type": "contact", "id": "66fd01239ffbe52cc8b3aa5e", "workspace_id": "this_is_an_id279_that_should_be_at_least_", "external_id": "70", "role": "user", "email": "joebloggs@intercom.io", "phone": null, "formatted_phone": null, "name": "joe bloggs", "avatar": null, "owner_id": null, "social_profiles": { "type": "list", "data": [] }, "has_hard_bounced": false, "marked_email_as_spam": false, "unsubscribed_from_emails": false, "created_at": 1727856931, "updated_at": 1727856931, "signed_up_at": 1727856931, "last_seen_at": null, "last_replied_at": null, "last_contacted_at": null, "last_email_opened_at": null, "last_email_clicked_at": null, "language_override": null, "browser": null, "browser_version": null, "browser_language": null, "os": null, "location": { "type": "location", "country": null, "region": null, "city": null, "country_code": null, "continent_code": null }, "android_app_name": null, "android_app_version": null, "android_device": null, "android_os_version": null, "android_sdk_version": null, "android_last_seen_at": null, "ios_app_name": null, "ios_app_version": null, "ios_device": null, "ios_os_version": null, "ios_sdk_version": null, "ios_last_seen_at": null, "custom_attributes": {}, "tags": { "type": "list", "data": [], "url": "/contacts/66fd01239ffbe52cc8b3aa5e/tags", "total_count": 0, "has_more": false }, "notes": { "type": "list", "data": [], "url": "/contacts/66fd01239ffbe52cc8b3aa5e/notes", "total_count": 0, "has_more": false }, "companies": { "type": "list", "data": [], "url": "/contacts/66fd01239ffbe52cc8b3aa5e/companies", "total_count": 0, "has_more": false }, "opted_out_subscription_types": { "type": "list", "data": [], "url": "/contacts/66fd01239ffbe52cc8b3aa5e/subscriptions", "total_count": 0, "has_more": false }, "opted_in_subscription_types": { "type": "list", "data": [], "url": "/contacts/66fd01239ffbe52cc8b3aa5e/subscriptions", "total_count": 0, "has_more": false }, "utm_campaign": null, "utm_content": null, "utm_medium": null, "utm_source": null, "utm_term": null, "referrer": null }
curl -i -X GET \ 'https://api.intercom.io/contacts/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
successful
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
The contacts phone number normalized to the E164 format
The id of an admin that has been assigned account ownership of the contact.
Whether the contact has marked an email sent to them as spam.
(UNIX timestamp) The time when the contact was created.
(UNIX timestamp) The time when the contact was last updated.
(UNIX timestamp) The time specified for when a contact signed up.
(UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
(UNIX timestamp) The time when the contact last messaged in.
(UNIX timestamp) The time when the contact was last messaged.
(UNIX timestamp) The time when the contact last opened an email.
(UNIX timestamp) The time when the contact last clicked a link in an email.
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
The version of the browser which the contact is using.
The language set by the browser which the contact is using.
The name of the Android app which the contact is using.
The version of the Android app which the contact is using.
The version of the Android OS which the contact is using.
The version of the Android SDK which the contact is using.
(UNIX timestamp) The time when the contact was last seen on an Android device.
The version of the iOS app which the contact is using.
The version of the iOS SDK which the contact is using.
(UNIX timestamp) The last time the contact used the iOS app.
An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.
{ "type": "contact", "id": "66fd01259ffbe52cc8b3aa5f", "workspace_id": "this_is_an_id283_that_should_be_at_least_", "external_id": "70", "role": "user", "email": "joe@bloggs.com", "phone": null, "formatted_phone": null, "name": "Joe Bloggs", "avatar": null, "owner_id": null, "social_profiles": { "type": "list", "data": [] }, "has_hard_bounced": false, "marked_email_as_spam": false, "unsubscribed_from_emails": false, "created_at": 1727856933, "updated_at": 1727856933, "signed_up_at": 1727856933, "last_seen_at": null, "last_replied_at": null, "last_contacted_at": null, "last_email_opened_at": null, "last_email_clicked_at": null, "language_override": null, "browser": null, "browser_version": null, "browser_language": null, "os": null, "location": { "type": "location", "country": null, "region": null, "city": null, "country_code": null, "continent_code": null }, "android_app_name": null, "android_app_version": null, "android_device": null, "android_os_version": null, "android_sdk_version": null, "android_last_seen_at": null, "ios_app_name": null, "ios_app_version": null, "ios_device": null, "ios_os_version": null, "ios_sdk_version": null, "ios_last_seen_at": null, "custom_attributes": {}, "tags": { "type": "list", "data": [], "url": "/contacts/66fd01259ffbe52cc8b3aa5f/tags", "total_count": 0, "has_more": false }, "notes": { "type": "list", "data": [], "url": "/contacts/66fd01259ffbe52cc8b3aa5f/notes", "total_count": 0, "has_more": false }, "companies": { "type": "list", "data": [], "url": "/contacts/66fd01259ffbe52cc8b3aa5f/companies", "total_count": 0, "has_more": false }, "opted_out_subscription_types": { "type": "list", "data": [], "url": "/contacts/66fd01259ffbe52cc8b3aa5f/subscriptions", "total_count": 0, "has_more": false }, "opted_in_subscription_types": { "type": "list", "data": [], "url": "/contacts/66fd01259ffbe52cc8b3aa5f/subscriptions", "total_count": 0, "has_more": false }, "utm_campaign": null, "utm_content": null, "utm_medium": null, "utm_source": null, "utm_term": null, "referrer": null }
curl -i -X DELETE \ 'https://api.intercom.io/contacts/{id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "id": "66fd01279ffbe52cc8b3aa60", "external_id": "70", "type": "contact", "deleted": true }
The unique identifier for the contact to merge away from. Must be a lead.
curl -i -X POST \ https://api.intercom.io/contacts/merge \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "from": "66fd01299ffbe52cc8b3aa61", "into": "66fd01299ffbe52cc8b3aa62" }'
successful
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
The contacts phone number normalized to the E164 format
The id of an admin that has been assigned account ownership of the contact.
Whether the contact has marked an email sent to them as spam.
(UNIX timestamp) The time when the contact was created.
(UNIX timestamp) The time when the contact was last updated.
(UNIX timestamp) The time specified for when a contact signed up.
(UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
(UNIX timestamp) The time when the contact last messaged in.
(UNIX timestamp) The time when the contact was last messaged.
(UNIX timestamp) The time when the contact last opened an email.
(UNIX timestamp) The time when the contact last clicked a link in an email.
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
The version of the browser which the contact is using.
The language set by the browser which the contact is using.
The name of the Android app which the contact is using.
The version of the Android app which the contact is using.
The version of the Android OS which the contact is using.
The version of the Android SDK which the contact is using.
(UNIX timestamp) The time when the contact was last seen on an Android device.
The version of the iOS app which the contact is using.
The version of the iOS SDK which the contact is using.
(UNIX timestamp) The last time the contact used the iOS app.
An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.
{ "type": "contact", "id": "66fd01299ffbe52cc8b3aa62", "workspace_id": "this_is_an_id291_that_should_be_at_least_", "external_id": "70", "role": "user", "email": "joe@bloggs.com", "phone": null, "formatted_phone": null, "name": "Joe Bloggs", "avatar": null, "owner_id": null, "social_profiles": { "type": "list", "data": [] }, "has_hard_bounced": false, "marked_email_as_spam": false, "unsubscribed_from_emails": false, "created_at": 1727856937, "updated_at": 1727856938, "signed_up_at": 1727856937, "last_seen_at": null, "last_replied_at": null, "last_contacted_at": null, "last_email_opened_at": null, "last_email_clicked_at": null, "language_override": null, "browser": null, "browser_version": null, "browser_language": null, "os": null, "location": { "type": "location", "country": null, "region": null, "city": null, "country_code": null, "continent_code": null }, "android_app_name": null, "android_app_version": null, "android_device": null, "android_os_version": null, "android_sdk_version": null, "android_last_seen_at": null, "ios_app_name": null, "ios_app_version": null, "ios_device": null, "ios_os_version": null, "ios_sdk_version": null, "ios_last_seen_at": null, "custom_attributes": {}, "tags": { "type": "list", "data": [], "url": "/contacts/66fd01299ffbe52cc8b3aa62/tags", "total_count": 0, "has_more": false }, "notes": { "type": "list", "data": [], "url": "/contacts/66fd01299ffbe52cc8b3aa62/notes", "total_count": 0, "has_more": false }, "companies": { "type": "list", "data": [], "url": "/contacts/66fd01299ffbe52cc8b3aa62/companies", "total_count": 0, "has_more": false }, "opted_out_subscription_types": { "type": "list", "data": [], "url": "/contacts/66fd01299ffbe52cc8b3aa62/subscriptions", "total_count": 0, "has_more": false }, "opted_in_subscription_types": { "type": "list", "data": [], "url": "/contacts/66fd01299ffbe52cc8b3aa62/subscriptions", "total_count": 0, "has_more": false }, "utm_campaign": null, "utm_content": null, "utm_medium": null, "utm_source": null, "utm_term": null, "referrer": null }
You can search for multiple contacts by the value of their attributes in order to fetch exactly who you want.
To search for contacts, you need to send a POST request to https://api.intercom.io/contacts/search.
This will accept a query object in the body which will define your filters in order to search for contacts.
Search queries can be complex, so optimizing them can help the performance of your search. Use the AND and OR operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is 50 results per page. See the pagination section for more details on how to use the starting_after param.
If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.
You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiple's there can be:
All timestamp fields (created_at, updated_at etc.) are indexed as Dates for Contact Search queries; Datetime queries are not currently supported. This means you can only query for timestamp fields by day - not hour, minute or second. For example, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM). The search results will then include Contacts created from January 2nd, 2020 12:00 AM onwards. If you'd like to get contacts created on January 1st, 2020 you should search with a created_at value equal (=) to 1577836800 (January 1st, 2020 12:00 AM). This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly.
Most key listed as part of the Contacts Model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as created_at accepts a date, the value cannot be a string such as "foorbar").
| Field | Type |
|---|---|
| id | String |
| role | String Accepts user or lead |
| name | String |
| avatar | String |
| owner_id | Integer |
| String | |
| email_domain | String |
| phone | String |
| formatted_phone | String |
| external_id | String |
| created_at | Date (UNIX Timestamp) |
| signed_up_at | Date (UNIX Timestamp) |
| updated_at | Date (UNIX Timestamp) |
| last_seen_at | Date (UNIX Timestamp) |
| last_contacted_at | Date (UNIX Timestamp) |
| last_replied_at | Date (UNIX Timestamp) |
| last_email_opened_at | Date (UNIX Timestamp) |
| last_email_clicked_at | Date (UNIX Timestamp) |
| language_override | String |
| browser | String |
| browser_language | String |
| os | String |
| location.country | String |
| location.region | String |
| location.city | String |
| unsubscribed_from_emails | Boolean |
| marked_email_as_spam | Boolean |
| has_hard_bounced | Boolean |
| ios_last_seen_at | Date (UNIX Timestamp) |
| 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 | Date (UNIX Timestamp) |
| android_app_version | String |
| android_device | String |
| android_app_name | String |
| andoid_sdk_version | String |
| segment_id | String |
| tag_id | String |
| custom_attributes.{attribute_name} | String |
You cannot use the <= or >= operators to search by created_at.
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 ("="). The operator has to be compatible with the field's type (eg. you cannot search with > for a given string value as it's only compatible for integer's and dates).
| Operator | Valid Types | Description |
|---|---|---|
| = | All | Equals |
| != | All | Doesn't Equal |
| IN | All | In Shortcut for OR queriesValues must be in Array |
| NIN | All | Not In Shortcut for OR ! queriesValues must be in Array |
| > | Integer Date (UNIX Timestamp) | Greater than |
| < | Integer Date (UNIX Timestamp) | Lower than |
| ~ | String | Contains |
| !~ | String | Doesn't Contain |
| ^ | String | Starts With |
| $ | String | Ends With |
Search using Intercoms Search APIs with a single filter.
The accepted operators you can use to define how you want to search for the value.
curl -i -X POST \ https://api.intercom.io/contacts/search \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "query": { "operator": "AND", "value": [ { "field": "created_at", "operator": ">", "value": "1306054154" } ] }, "pagination": { "per_page": 5 } }'
{ "type": "list", "data": [], "total_count": 0, "pages": { "type": "pages", "page": 1, "per_page": 5, "total_pages": 0 } }
You can fetch a list of all contacts (ie. users or leads) in your workspace.
You can use pagination to limit the number of results returned. The default is 50 results per page. See the pagination section for more details on how to use the starting_after param.
curl -i -X GET \ https://api.intercom.io/contacts \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "type": "list", "data": [], "total_count": 0, "pages": { "type": "pages", "page": 1, "per_page": 10, "total_pages": 0 } }
Payload to create a contact
Payload to create a contact
An image URL containing the avatar of a contact
The time specified for when a contact signed up
The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually)
The id of an admin that has been assigned account ownership of the contact
Whether the contact is unsubscribed from emails
curl -i -X POST \ https://api.intercom.io/contacts \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Content-Type: application/json' \ -H 'Intercom-Version: Unstable' \ -d '{ "email": "joebloggs@intercom.io" }'
successful
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
The contacts phone number normalized to the E164 format
The id of an admin that has been assigned account ownership of the contact.
Whether the contact has marked an email sent to them as spam.
(UNIX timestamp) The time when the contact was created.
(UNIX timestamp) The time when the contact was last updated.
(UNIX timestamp) The time specified for when a contact signed up.
(UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
(UNIX timestamp) The time when the contact last messaged in.
(UNIX timestamp) The time when the contact was last messaged.
(UNIX timestamp) The time when the contact last opened an email.
(UNIX timestamp) The time when the contact last clicked a link in an email.
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
The version of the browser which the contact is using.
The language set by the browser which the contact is using.
The name of the Android app which the contact is using.
The version of the Android app which the contact is using.
The version of the Android OS which the contact is using.
The version of the Android SDK which the contact is using.
(UNIX timestamp) The time when the contact was last seen on an Android device.
The version of the iOS app which the contact is using.
The version of the iOS SDK which the contact is using.
(UNIX timestamp) The last time the contact used the iOS app.
An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.
{ "type": "contact", "id": "66fd01309ffbe52cc8b3aa65", "workspace_id": "this_is_an_id303_that_should_be_at_least_", "external_id": null, "role": "user", "email": "joebloggs@intercom.io", "phone": null, "formatted_phone": null, "name": null, "avatar": null, "owner_id": null, "social_profiles": { "type": "list", "data": [] }, "has_hard_bounced": false, "marked_email_as_spam": false, "unsubscribed_from_emails": false, "created_at": 1727856944, "updated_at": 1727856944, "signed_up_at": null, "last_seen_at": null, "last_replied_at": null, "last_contacted_at": null, "last_email_opened_at": null, "last_email_clicked_at": null, "language_override": null, "browser": null, "browser_version": null, "browser_language": null, "os": null, "location": { "type": "location", "country": null, "region": null, "city": null, "country_code": null, "continent_code": null }, "android_app_name": null, "android_app_version": null, "android_device": null, "android_os_version": null, "android_sdk_version": null, "android_last_seen_at": null, "ios_app_name": null, "ios_app_version": null, "ios_device": null, "ios_os_version": null, "ios_sdk_version": null, "ios_last_seen_at": null, "custom_attributes": {}, "tags": { "type": "list", "data": [], "url": "/contacts/66fd01309ffbe52cc8b3aa65/tags", "total_count": 0, "has_more": false }, "notes": { "type": "list", "data": [], "url": "/contacts/66fd01309ffbe52cc8b3aa65/notes", "total_count": 0, "has_more": false }, "companies": { "type": "list", "data": [], "url": "/contacts/66fd01309ffbe52cc8b3aa65/companies", "total_count": 0, "has_more": false }, "opted_out_subscription_types": { "type": "list", "data": [], "url": "/contacts/66fd01309ffbe52cc8b3aa65/subscriptions", "total_count": 0, "has_more": false }, "opted_in_subscription_types": { "type": "list", "data": [], "url": "/contacts/66fd01309ffbe52cc8b3aa65/subscriptions", "total_count": 0, "has_more": false }, "utm_campaign": null, "utm_content": null, "utm_medium": null, "utm_source": null, "utm_term": null, "referrer": null }
curl -i -X GET \ 'https://api.intercom.io/contacts/find_by_external_id/{external_id}' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
successful
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
The contacts phone number normalized to the E164 format
The id of an admin that has been assigned account ownership of the contact.
Whether the contact has marked an email sent to them as spam.
(UNIX timestamp) The time when the contact was created.
(UNIX timestamp) The time when the contact was last updated.
(UNIX timestamp) The time specified for when a contact signed up.
(UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
(UNIX timestamp) The time when the contact last messaged in.
(UNIX timestamp) The time when the contact was last messaged.
(UNIX timestamp) The time when the contact last opened an email.
(UNIX timestamp) The time when the contact last clicked a link in an email.
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
The version of the browser which the contact is using.
The language set by the browser which the contact is using.
The name of the Android app which the contact is using.
The version of the Android app which the contact is using.
The version of the Android OS which the contact is using.
The version of the Android SDK which the contact is using.
(UNIX timestamp) The time when the contact was last seen on an Android device.
The version of the iOS app which the contact is using.
The version of the iOS SDK which the contact is using.
(UNIX timestamp) The last time the contact used the iOS app.
An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.
{ "type": "contact", "id": "66fd01329ffbe52cc8b3aa66", "workspace_id": "this_is_an_id307_that_should_be_at_least_", "external_id": "70", "role": "user", "email": "joe@bloggs.com", "phone": null, "formatted_phone": null, "name": "Joe Bloggs", "avatar": null, "owner_id": null, "social_profiles": { "type": "list", "data": [] }, "has_hard_bounced": false, "marked_email_as_spam": false, "unsubscribed_from_emails": false, "created_at": 1727856946, "updated_at": 1727856946, "signed_up_at": 1727856946, "last_seen_at": null, "last_replied_at": null, "last_contacted_at": null, "last_email_opened_at": null, "last_email_clicked_at": null, "language_override": null, "browser": null, "browser_version": null, "browser_language": null, "os": null, "location": { "type": "location", "country": null, "region": null, "city": null, "country_code": null, "continent_code": null }, "android_app_name": null, "android_app_version": null, "android_device": null, "android_os_version": null, "android_sdk_version": null, "android_last_seen_at": null, "ios_app_name": null, "ios_app_version": null, "ios_device": null, "ios_os_version": null, "ios_sdk_version": null, "ios_last_seen_at": null, "custom_attributes": {}, "tags": { "type": "list", "data": [], "url": "/contacts/66fd01329ffbe52cc8b3aa66/tags", "total_count": 0, "has_more": false }, "notes": { "type": "list", "data": [], "url": "/contacts/66fd01329ffbe52cc8b3aa66/notes", "total_count": 0, "has_more": false }, "companies": { "type": "list", "data": [], "url": "/contacts/66fd01329ffbe52cc8b3aa66/companies", "total_count": 0, "has_more": false }, "opted_out_subscription_types": { "type": "list", "data": [], "url": "/contacts/66fd01329ffbe52cc8b3aa66/subscriptions", "total_count": 0, "has_more": false }, "opted_in_subscription_types": { "type": "list", "data": [], "url": "/contacts/66fd01329ffbe52cc8b3aa66/subscriptions", "total_count": 0, "has_more": false }, "utm_campaign": null, "utm_content": null, "utm_medium": null, "utm_source": null, "utm_term": null, "referrer": null }
curl -i -X POST \ 'https://api.intercom.io/contacts/{id}/archive' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "id": "66fd01349ffbe52cc8b3aa68", "external_id": "70", "type": "contact", "archived": true }
curl -i -X POST \ 'https://api.intercom.io/contacts/{id}/unarchive' \ -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \ -H 'Intercom-Version: Unstable'
{ "id": "66fd01369ffbe52cc8b3aa69", "external_id": "70", "type": "contact", "archived": false }