Skip to content
Home/
REST API Reference
/
/
List all contacts

List all contacts

Request

You can fetch a list of all contacts (ie. users or leads) in your workspace.

Merged contacts

Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.

Pagination

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 for more details on how to use the starting_after param.

Requires the read_users_companies or read_write_users OAuth scope.

Security
bearerAuth
Query
include_merge_historyboolean

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.

Default:false
escape_identityboolean

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.

Default:true
per_pageinteger, [ 1 .. 150 ]

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.

Default:10
starting_afterstring

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.

Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:2.17
curl -i -X GET \
  'https://api.intercom.io/contacts?include_merge_history=false&escape_identity=true&per_page=10&starting_after=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.17'

Responses

successful

Bodyapplication/json
typestring

Always list

Value:"list"
Example:"list"
dataArray of objects(Contact)

The list of contact objects

total_countinteger

A count of the total number of objects.

Example:100
pagesobject or null(Cursor based pages)

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.

Response
{
  "type": "list",
  "data": [],
  "total_count": 0,
  "pages": {
    "type": "pages",
    "page": 1,
    "per_page": 10,
    "total_pages": 0
  }
}