# List all contacts

You can fetch a list of all contacts (ie. users or leads) in your workspace.
Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
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.
Requires the `read_users_companies` or `read_write_users` OAuth scope.

Endpoint: GET /contacts
Version: 2.17
Security: bearerAuth

## Query parameters:

  - `include_merge_history` (boolean)
    Pass `true` to include a `merge_history` array on each contact in the response. Returned for contacts of any role, with at most the 10 most recent merges.

  - `escape_identity` (boolean)
    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.

  - `per_page` (integer)
    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`.

  - `starting_after` (string)
    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`.

## Header parameters:

  - `Intercom-Version` (string)

## Response 200 fields (application/json):

  - `type` (string)
    Always list
    Enum: "list"

  - `data` (array)
    The list of contact objects

  - `data.type` (string)
    The type of object.
    Example: contact

  - `data.id` (string)
    The unique identifier for the contact which is given by Intercom.
    Example: 5ba682d23d7cf92bef87bfd4

  - `data.external_id` (string)
    The unique identifier for the contact which is provided by the Client.
    Example: f3b87a2e09d514c6c2e79b9a

  - `data.workspace_id` (string)
    The id of the workspace which the contact belongs to.
    Example: ecahpwf5

  - `data.role` (string)
    The role of the contact.
    Example: user

  - `data.email` (string)
    The contact's email.
    Example: joe@example.com

  - `data.email_domain` (string)
    The contact's email domain.
    Example: example.com

  - `data.email_verified` (boolean)
    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

  - `data.phone` (string)
    The contacts phone.
    Example: +1123456789

  - `data.name` (string)
    The contacts name.
    Example: John Doe

  - `data.owner_id` (string)
    The id of an admin that has been assigned account ownership of the contact.
    Example: 321

  - `data.has_hard_bounced` (boolean)
    Whether the contact has had an email sent to them hard bounce.
    Example: true

  - `data.marked_email_as_spam` (boolean)
    Whether the contact has marked an email sent to them as spam.
    Example: true

  - `data.unsubscribed_from_emails` (boolean)
    Whether the contact is unsubscribed from emails.
    Example: true

  - `data.created_at` (integer)
    (Unix timestamp in seconds) The time when the contact was created.
    Example: 1571672154

  - `data.updated_at` (integer)
    (Unix timestamp in seconds) The time when the contact was last updated.
    Example: 1571672154

  - `data.signed_up_at` (integer)
    (Unix timestamp in seconds) The time specified for when a contact signed up.
    Example: 1571672154

  - `data.last_seen_at` (integer)
    (Unix timestamp in seconds) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
    Example: 1571672154

  - `data.last_replied_at` (integer)
    (Unix timestamp in seconds) The time when the contact last messaged in.
    Example: 1571672154

  - `data.last_contacted_at` (integer)
    (Unix timestamp in seconds) The time when the contact was last messaged.
    Example: 1571672154

  - `data.last_email_opened_at` (integer)
    (Unix timestamp in seconds) The time when the contact last opened an email.
    Example: 1571672154

  - `data.last_email_clicked_at` (integer)
    (Unix timestamp in seconds) The time when the contact last clicked a link in an email.
    Example: 1571672154

  - `data.language_override` (string)
    A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
    Example: en

  - `data.browser` (string)
    The name of the browser which the contact is using.
    Example: Chrome

  - `data.browser_version` (string)
    The version of the browser which the contact is using.
    Example: 80.0.3987.132

  - `data.browser_language` (string)
    The language set by the browser which the contact is using.
    Example: en-US

  - `data.os` (string)
    The operating system which the contact is using.
    Example: Mac OS X

  - `data.android_app_name` (string)
    The name of the Android app which the contact is using.
    Example: Intercom

  - `data.android_app_version` (string)
    The version of the Android app which the contact is using.
    Example: 5.0.0

  - `data.android_device` (string)
    The Android device which the contact is using.
    Example: Pixel 3

  - `data.android_os_version` (string)
    The version of the Android OS which the contact is using.
    Example: 10

  - `data.android_sdk_version` (string)
    The version of the Android SDK which the contact is using.
    Example: 28

  - `data.android_last_seen_at` (integer)
    (Unix timestamp in seconds) The time when the contact was last seen on an Android device.
    Example: 1571672154

  - `data.ios_app_name` (string)
    The name of the iOS app which the contact is using.
    Example: Intercom

  - `data.ios_app_version` (string)
    The version of the iOS app which the contact is using.
    Example: 5.0.0

  - `data.ios_device` (string)
    The iOS device which the contact is using.
    Example: iPhone 11

  - `data.ios_os_version` (string)
    The version of iOS which the contact is using.
    Example: 13.3.1

  - `data.ios_sdk_version` (string)
    The version of the iOS SDK which the contact is using.
    Example: 13.3.1

  - `data.ios_last_seen_at` (integer)
    (Unix timestamp in seconds) The last time the contact used the iOS app.
    Example: 1571672154

  - `data.custom_attributes` (object)
    The custom attributes which are set for the contact.

  - `data.avatar` (string)
    An image URL containing the avatar of a contact.
    Example: https://example.org/128Wash.jpg

  - `data.tags` (object)
    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.

  - `data.tags.data` (array)
    This object represents the tags attached to a contact.

  - `data.tags.data.type` (string)
    The addressable object type
    Example: note

  - `data.tags.data.id` (string)
    The id of the addressable object
    Example: 123

  - `data.tags.data.url` (string)
    Url to get more company resources for this contact
    Example: /contacts/5ba682d23d7cf92bef87bfd4/notes

  - `data.tags.url` (string)
    url to get more tag resources for this contact
    Example: /contacts/5ba682d23d7cf92bef87bfd4/tags

  - `data.tags.total_count` (integer)
    Int representing the total number of tags attached to this contact
    Example: 100

  - `data.tags.has_more` (boolean)
    Whether there's more Addressable Objects to be viewed. If true, use the url to view all
    Example: true

  - `data.notes` (object)
    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.

  - `data.notes.data` (array)
    This object represents the notes attached to a contact.

  - `data.notes.url` (string)
    Url to get more company resources for this contact
    Example: /contacts/5ba682d23d7cf92bef87bfd4/notes

  - `data.notes.total_count` (integer)
    Int representing the total number of companyies attached to this contact
    Example: 100

  - `data.notes.has_more` (boolean)
    Whether there's more Addressable Objects to be viewed. If true, use the url to view all
    Example: true

  - `data.companies` (object)
    An object with metadata about companies attached to a contact . Up to 10 will be displayed here. Use the url to get more.

  - `data.companies.data` (array)
    An array of company data objects attached to the contact.

  - `data.companies.data.id` (string)
    The unique identifier for the company which is given by Intercom.
    Example: 5ba682d23d7cf92bef87bfd4

  - `data.companies.data.type` (string)
    The type of the object. Always company.
    Enum: "company"

  - `data.companies.data.url` (string)
    The relative URL of the company.
    Example: /companies/5ba682d23d7cf92bef87bfd4

  - `data.companies.url` (string)
    Url to get more company resources for this contact
    Example: /contacts/5ba682d23d7cf92bef87bfd4/companies

  - `data.companies.total_count` (integer)
    Integer representing the total number of companies attached to this contact
    Example: 100

  - `data.companies.has_more` (boolean)
    Whether there's more Addressable Objects to be viewed. If true, use the url to view all
    Example: true

  - `data.location` (object)
    An object containing location meta data about a Intercom contact.

  - `data.location.type` (string)
    Always location
    Example: location

  - `data.location.country` (string)
    The country that the contact is located in
    Example: Ireland

  - `data.location.region` (string)
    The overal region that the contact is located in
    Example: Dublin

  - `data.location.city` (string)
    The city that the contact is located in
    Example: Dublin

  - `data.location.country_code` (string)
    The ISO 3166-1 alpha-3 code of the country that the contact is located in
    Example: IRL

  - `data.location.continent_code` (string)
    The code of the continent that the contact is located in
    Example: EU

  - `data.social_profiles` (object)
    An object containing social profiles that a contact has.

  - `data.social_profiles.data` (array)
    A list of social profiles objects associated with the contact.

  - `data.social_profiles.data.type` (string)
    value is "social_profile"
    Example: social_profile

  - `data.social_profiles.data.name` (string)
    The name of the Social media profile
    Example: Facebook

  - `data.social_profiles.data.url` (string)
    The name of the Social media profile
    Example: http://twitter.com/th1sland

  - `data.opted_out_subscription_types` (object)
    An object containing Subscription Types meta data about the SubscriptionTypes that a contact has.

  - `data.opted_out_subscription_types.type` (string)
    The type of the object
    Enum: "list"

  - `data.opted_out_subscription_types.data` (array)
    This object represents the subscriptions attached to a contact.

  - `data.opted_out_subscription_types.url` (string)
    Url to get more subscription type resources for this contact
    Example: /contacts/5ba682d23d7cf92bef87bfd4/subscriptions

  - `data.opted_out_subscription_types.total_count` (integer)
    Int representing the total number of subscription types attached to this contact
    Example: 100

  - `data.opted_out_subscription_types.has_more` (boolean)
    Whether there's more Addressable Objects to be viewed. If true, use the url to view all
    Example: true

  - `data.utm_campaign` (string)
    The `utm_campaign` value recorded for the contact.
    Example: spring_launch

  - `data.utm_content` (string)
    The `utm_content` value recorded for the contact.
    Example: banner_ad

  - `data.utm_medium` (string)
    The `utm_medium` value recorded for the contact.
    Example: email

  - `data.utm_source` (string)
    The `utm_source` value recorded for the contact.
    Example: newsletter

  - `data.utm_term` (string)
    The `utm_term` value recorded for the contact.
    Example: support_software

  - `data.referrer` (string)
    The URL of the page the contact came from, as recorded by the Messenger.
    Example: https://example.com/pricing

  - `data.sms_consent` (boolean)
    Whether the contact has consented to receive SMS messages.
    Example: false

  - `data.unsubscribed_from_sms` (boolean)
    Whether the contact is unsubscribed from SMS messages.
    Example: false

  - `data.enabled_push_messaging` (boolean)
    Whether the contact has a mobile device registered to receive push messages.
    Example: true

  - `data.merge_history` (array)
    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.

  - `data.merge_history.type` (string)
    The type of object.
    Example: merge_history

  - `data.merge_history.source_contact_id` (string)
    The Intercom ID of the contact that was merged into this contact.
    Example: 5ba682d23d7cf92bef87bfd3

  - `data.merge_history.source_contact_role` (string)
    The role of the contact that was merged in.
    Enum: "lead", "user"

  - `data.merge_history.merged_at` (integer)
    (Unix timestamp in seconds) The time when the merge occurred.
    Example: 1571672154

  - `total_count` (integer)
    A count of the total number of objects.
    Example: 100

  - `pages` (object)
    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.

  - `pages.type` (string)
    the type of object `pages`.
    Enum: "pages"

  - `pages.page` (integer)
    The current page
    Example: 1

  - `pages.next` (object)
    Fetch the next page by sending this `starting_after` cursor. Omitted on the last page.

  - `pages.next.page` (integer)
    The number of the next page
    Example: 2

  - `pages.next.starting_after` (string)
    The cursor to send in the next request to get the next page of results.
    Example: your-cursor-from-response

  - `pages.per_page` (integer)
    Number of results per page
    Example: 2

  - `pages.total_pages` (integer)
    Total number of pages
    Example: 13

## Response 400 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (any, required)
    A string indicating the kind of error, used to further qualify the HTTP response code. A few request validation errors send an HTTP status code as an integer here instead, for example `422`.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: error.list

  - `request_id` (string)
    Example: f93ecfa8-d08a-4325-8694-89aeb89c8f85

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (any, required)
    A string indicating the kind of error, used to further qualify the HTTP response code. A few request validation errors send an HTTP status code as an integer here instead, for example `422`.
    Example: unauthorized

  - `errors.message` (string)
    Optional. Human readable description of the error.
    Example: Access Token Invalid