Bulk update companies

Request

You can bulk update companies by submitting an array of company objects with the fields to update. Each company must include an id field identifying the company to update by its Intercom company id. An unknown id fails that item and never creates a company.

Only the fields listed in the request schema below can be set. Any other fields in a company object are ignored.

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

Limits

Maximum of 100 companies 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

companiesArray of objects, <= 100 itemsrequired

An array of company objects to update. Each must include an id and the fields to update. Maximum 100 companies per request.

jobobject

Optional. Include to append tasks to an existing job.

curl -i -X PUT \
  https://api.intercom.io/companies/bulk \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "companies": [
      {
        "id": "531ee472cce572a6ec000006",
        "name": "Acme Corp",
        "plan": "Enterprise",
        "size": 100,
        "website": "https://www.example.com",
        "industry": "Manufacturing",
        "monthly_spend": 1000,
        "remote_created_at": 1394531169,
        "update_last_request_at": true,
        "custom_attributes": {
          "paid_subscriber": true,
          "team_mates": 9
        }
      },
      {
        "id": "531ee472cce572a6ec000007",
        "name": "Example Inc"
      }
    ]
  }'

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