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 100 contacts per request.
You can append tasks to an existing job by including job.id in the request body.

Security

bearerAuth

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"Preview"

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, <= 100 itemsrequired

An array of contacts to delete, each identified by id. Maximum 100 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:"pending""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 job completed as a Unix timestamp. Null if not yet completed.

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"
}