DocsBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreForumBlogYour Apps

List attached contacts

Example Request & Response

$ curl https://api.intercom.io/companies/<id>/contacts \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept:application/json'
HTTP/1.1 200 OK
{
  "type": "list",
  "data": [
    {
      "type": "contact",
      "id": "5ba682d23d7cf92bef87bfd4",
      "workspace_id": "ecahpwf5",
      "external_id": "25",
      "role": "user",
      "email": "[email protected]",
      "phone": "+1123456789",
      "name": "Hoban Washburn",
      "avatar": "https://example.org/128Wash.jpg",
      "owner_id": 127,
      "social_profiles": {
        "type": "list",
        "data": [
          {
            "type": "social_profile",
            "name": "Twitter",
            "url": "http://twitter.com/th1sland"
          }
        ]
      },
      "unsubscribed_from_emails": false,
      "created_at": 1571672154,
      "updated_at": 1571672158,
      "signed_up_at": 1571069751,
      "last_seen_at": 1571069751,
      "last_replied_at": 1571672158,
      "last_contacted_at": 1571672158,
      "last_email_opened_at": 1571673478,
      "last_email_clicked_at": 1571676789,
      "language_override": null,
      "browser": "chrome",
      "browser_version": "77.0.3865.90",
      "browser_language": "en",
      "os": "OS X 10.14.6",
      "location": {
        "type": "location",
        "country": "Ireland",
        "region": "Dublin",
        "city": "Dublin"
      },
      "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": {
        "paid_subscriber": true,
        "monthly_spend": 155.5,
        "team_mates": 1
      },
      "tags": {
        "type": "list",
        "data": [
          {
            "type": "tag",
            "id": "2",
            "url": "/tags/2"
          },
          {
            "type": "tag",
            "id": "4",
            "url": "/tags/4"
          },
          {
            "type": "tag",
            "id": "5",
            "url": "/tags/5"
          }
        ],
        "url": "/contacts/5ba682d23d7cf92bef87bfd4/tags"
      },
      "notes": {
        "type": "list",
        "data": [
          {
            "type": "note",
            "id": "20114858",
            "url": "/notes/20114858"
          }
        ],
        "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes"
      },
      "companies": {
        "type": "list",
        "data": [
          {
            "type": "company",
            "id": "5ba686093d7cf93552a3dc99",
            "url": "/companies/5ba686093d7cf93552a3dc99"
          },
          {
            "type": "company",
            "id": "5cee64a03d7cf90c51b36f19",
            "url": "/companies/5cee64a03d7cf90c51b36f19"
          },
          {
            "type": "company",
            "id": "5d7668883d7cf944dbc5c791",
            "url": "/companies/5d7668883d7cf944dbc5c791"
          }
        ],
        "url": "/contacts/5ba682d23d7cf92bef87bfd4/companies"
      }
    }
  ],
  "total_count": 436,
  "pages": {
    "type": "pages",
    "next": {
      "page": 2,
      "starting_after": "WzE1NzEzMTc0NDYwMDAsIjViYTY4MmQyM2Q3Y2Y5MmJlZjg3YmZkNCIsMl0="
    },
    "page": 1,
    "per_page": 1,
    "total_pages": 436
  }
}
Example Errors

HTTP/1.1 400 BAD REQUEST
{
  "type": "error.list",
  "request_id": "000nbboasf1qqab6b910",
  "errors": [
    {
      "code": "client_error",
      "message": "Invalid starting_after param. Please try again using a starting_after value from a paginated response"
    }
  ]
}

You can fetch a list of all contacts that belong to a company.

Response

This will return a paginated list of Contact objects.

Attribute

Type

Description

type

String

The type of object - list

data

Array

An array containing Contact Objects

total_count

Integer

The total number of contacts

pages

Pagination Object

The information needed to paginate through contacts