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

List deleted contacts

Request

Fetch a paginated list of the contacts in your workspace that are no longer active, so you can recover ones whose id, email, or external_id you no longer have and then permanently delete them. Each entry carries a status describing why the contact is inactive: archived, blocked, merged, pending_deletion, or permanently_deleted. merged_into_id is present only when status is merged, and external_id and email are null for permanently_deleted contacts.

Requires the read_users_companies or read_write_users OAuth scope.

Security
bearerAuth
Query
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
pageinteger, >= 1

The page of results to fetch. Defaults to 1.

Default:1
escape_identityboolean

By default, email values in the response are HTML-escaped (for example, & is returned as &). Pass false to return them unescaped.

Default:true
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/deleted?per_page=10&page=1&escape_identity=true' \
  -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(Deleted Contact)

The list of deleted contact objects.

Example:
[
  {
    "type": "contact",
    "id": "5ba682d23d7cf92bef87bfd4",
    "external_id": "70",
    "email": "joe@example.com",
    "role": "user",
    "status": "archived",
    "updated_at": 1756636800
  }
]
total_countinteger

A count of the total number of deleted contacts.

Example:100
pagesobject

Offset-based pagination metadata.

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