# 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  results per page.
  See the pagination section for more details on how to use the  param.
{% /admonition %}


Endpoint: GET /contacts
Version: 2.13
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", "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: "70"

  - `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 containing companies meta data about the companies that a contact has. 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.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://twitter.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 .
    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"