Intercom API (unofficial showcase)
POST/contacts/bulk/delete

Bulk delete contacts

Deletes multiple contacts permanently through an asynchronous job. Include up to 100 contact identifiers in contacts; an item that cannot be deleted fails independently, while the job continues processing other items. Use the returned job ID with GET /contacts/bulk/{id} to monitor the job and check for item failures.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 2 body fields
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Bulk contact deletion request. Include the required contacts array with no more than 100 contact objects; optionally include job to append tasks to an existing job.

contactsarray<object>required
An array of contacts to delete, each identified by `id`. Maximum 100 contacts per request.
jobobjectoptional
Optional. Include to append tasks to an existing job.

5 status codes
202Returns the asynchronous bulk job object, including its identifier, current state, task details, and status URL.
idstringoptional
The unique identifier for the bulk job.
typestringoptional
The type of the object.
Allowed:contacts.bulk.job
statestringoptional
The current state of the job.
Allowed:pendingrunningcompletedcompleted_with_errors
created_atintegeroptional
The time the job was created as a Unix timestamp.
updated_atintegeroptional
The time the job was last updated as a Unix timestamp.
completed_atintegeroptional
The time the job completed as a Unix timestamp. Null if not yet completed.
tasksarray<object>optional
The tasks that make up this bulk job.
urlstringoptional
The URL to check the job status.
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
403Returned when the request is forbidden.

One documented failure

  • forbidden

    job job_v2_1 is closed for new task updates

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
404Returned when a requested resource is not found.

One documented failure

  • job_not_found

    job job_v2_1 not found

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
422Returned when the request cannot be processed, including when the contact list is missing or exceeds the 100-item limit.

3 documented failures

  • field_not_found

    contacts field must be supplied

  • parameter_invalid

    maximum number of contacts per request is 100

  • type_mismatch

    contacts must be an array

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 401 is returned when the request is unauthorized, a 403 when the request is forbidden, and a 404 when a requested resource is not found. A 422 is returned when the request cannot be processed, such as when contacts is missing or contains more than 100 items. Each item in contacts must include an id identifying the contact to delete.