Skip to content

Bulk delete companies

Request

You can bulk delete companies by submitting an array of companies, each identified by its Intercom company id. Each company is permanently deleted, the same as with the single Delete a company endpoint. This can't be reversed.

If the workspace is under a legal hold, each item is rejected and the job's state ends as completed_with_errors.

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

Limits
  • Maximum of 1,000 companies per request.
  • You can append tasks to an existing job by including job.id in the request body.
Security
bearerAuth
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:Preview
Bodyapplication/json
companiesArray of objects, <= 1000 itemsrequired

An array of companies to delete, each identified by its Intercom company id. Maximum 1,000 companies per request.

jobobject

Optional. Include to append tasks to an existing job.

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

Responses

Accepted

Bodyapplication/json
idstring

The unique identifier for the bulk job.

Example:"job_v2_1"
typestring

The type of the object.

Value:"companies.bulk.job"
Example:"companies.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/companies/bulk/job_v2_1"
Response
{ "id": "job_v2_1", "type": "companies.bulk.job", "state": "running", "created_at": 1713360000, "updated_at": 1713360060, "completed_at": null, "tasks": [ { … } ], "url": "https://api.intercom.io/companies/bulk/job_v2_1" }