Bulk create or update companies

Request

You can bulk create or update companies by submitting an array of company objects. Each company is matched on the company_id you have defined for it: a new company is created if none exists with that company_id, otherwise the matching company is updated. This mirrors the single Create or update a company endpoint.

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

Handling failures

If an item fails validation, that item is rejected and the job's state ends as completed_with_errors. The other companies in the same request are still processed. The job state from GET /companies/bulk/{id} is the signal that one or more items were rejected.

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 create or update. Maximum 100 companies per request.

jobobject

Optional. Include to append tasks to an existing job.

curl -i -X POST \
  https://api.intercom.io/companies/bulk \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "companies": [
      {
        "company_id": "abc123",
        "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
        }
      },
      {
        "company_id": "def456",
        "name": "Example Inc",
        "industry": "Manufacturing"
      }
    ]
  }'

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