Bulk delete contacts

Request

You can delete contacts in bulk by submitting an array of contact ids.

The endpoint creates an async job that processes the deletes in the background. Use the returned job ID with GET /contacts/bulk/{id} to check the job status.

Permanent deletion

A contact that doesn't exist, or can't be deleted, fails that item and the job's state ends as completed_with_errors (visible via GET /contacts/bulk/{id}) without failing the rest of the batch.

Limits

Maximum of 1,000 contacts per request.
You can append tasks to an existing job by including job.id in the request body.

Requires the read_write_users or write_users_companies OAuth scope.

Security

bearerAuth

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:Preview

Bodyapplication/json

contactsArray of objects, <= 1000 itemsrequired

An array of contacts to delete, each identified by id. Maximum 1,000 contacts per request.

jobobject

Optional. Include to append tasks to an existing job.

curl -i -X POST \
  https://api.intercom.io/contacts/bulk/delete \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "contacts": [
      {
        "id": "abc123"
      },
      {
        "id": "def456"
      }
    ]
  }'

Responses

Accepted

Bodyapplication/json

idstring

The unique identifier for the bulk job.

Example:"job_v2_1"

typestring

The type of the object.

Value:"contacts.bulk.job"

Example:"contacts.bulk.job"

statestring

The current state of the job.

Enum:"running""completed""completed_with_errors"

Example:"running"

created_atinteger, (date-time)

The time the job was created as a Unix timestamp.

Example:1713360000

updated_atinteger, (date-time)

The time the job was last updated as a Unix timestamp.

Example:1713360060

completed_atinteger or null, (date-time)

The time the most recent task completed as a Unix timestamp. Set as soon as any task completes, so check state to know whether the whole job has finished. Null until a task completes.

Example:1713360120

tasksArray of objects

The tasks that make up this bulk job.

urlstring

The URL to check the job status.

Example:"https://api.intercom.io/contacts/bulk/job_v2_1"

Response

{
  "id": "job_v2_3",
  "type": "contacts.bulk.job",
  "state": "running",
  "created_at": 1713360000,
  "updated_at": 1713360060,
  "completed_at": null,
  "tasks": [
    { … }
  ],
  "url": "https://api.intercom.io/contacts/bulk/job_v2_3"
}