# List all contacts

You can fetch a list of all contacts (ie. users or leads) in your workspace.
{% admonition type="warning" name="Pagination" %}
  You can use pagination to limit the number of results returned. The default is 50 results per page.
  See the pagination section for more details on how to use the starting_after param.
{% /admonition %}

Endpoint: GET /contacts
Version: 2.14
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)
    Intercom API version.By default, it's equal to the version set in the app package.
    Enum: "1.0", "1.1", "1.2", "1.3", "1.4", "2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13", "2.14", "Unstable"

## 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,null)
    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.phone` (string,null)
    The contacts phone.
    Example: "+1123456789"

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

  - `data.owner_id` (integer,null)
    The id of an admin that has been assigned account ownership of the contact.
    Example: 123

  - `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) The time when the contact was created.
    Example: 1571672154

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

  - `data.signed_up_at` (integer,null)
    (UNIX timestamp) The time specified for when a contact signed up.
    Example: 1571672154

  - `data.last_seen_at` (integer,null)
    (UNIX timestamp) 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,null)
    (UNIX timestamp) The time when the contact last messaged in.
    Example: 1571672154

  - `data.last_contacted_at` (integer,null)
    (UNIX timestamp) The time when the contact was last messaged.
    Example: 1571672154

  - `data.last_email_opened_at` (integer,null)
    (UNIX timestamp) The time when the contact last opened an email.
    Example: 1571672154

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `data.ios_last_seen_at` (integer,null)
    (UNIX timestamp) 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` (object,null)

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

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

  - `data.tags` (object,null)
    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.total_count` (integer)
    Int representing the total number of companyies attached to this contact
    Example: 100

  - `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.total_count` (integer)
    Integer representing the total number of companies attached to this contact
    Example: 100

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

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

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

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

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

  - `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://example.com/th1sland"

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

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

  - `pages.next.per_page` (integer)
    The number of results to fetch per page.
    Example: 2

  - `pages.next.starting_after` (string,null)
    The cursor to use 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 401 fields (application/json):

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

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

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

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code
    Example: "unauthorized"

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

  - `errors.field` (string,null)
    Optional. Used to identify a particular field or query parameter that was in error.
    Example: "email"