Bulk update contacts

Request

You can bulk update contacts by submitting an array of contact objects with the fields to update. Each contact must include an id field identifying the contact to update. You can also add or remove tags on each contact by including a tags object.

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

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

Limits

Maximum of 100 contacts per request.
You can append tasks to an existing job by including job.id in the request body.
Tag application is best-effort and processed asynchronously: unknown tag IDs are skipped, and per-tag results are not returned in the job status.

Requires the read_write_users or write_users_companies OAuth scope.

Security

bearerAuth

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:2.17

Bodyapplication/json

contactsArray of objects, <= 100 itemsrequired

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

jobobject

Optional. Include to append tasks to an existing job.

curl -i -X PUT \
  https://api.intercom.io/contacts/bulk \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.17' \
  -d '{
    "contacts": [
      {
        "id": "abc123",
        "external_id": "ext123",
        "email": "joe@bloggs.com",
        "name": "Joe Bloggs",
        "phone": "+353871234567",
        "avatar": "https://www.example.com/avatar_image.jpg",
        "owner_id": "321",
        "unsubscribed_from_emails": false,
        "language_override": "fr",
        "custom_attributes": {
          "plan": "pro"
        },
        "companies": [
          {
            "company_id": "6",
            "name": "Blue Sun"
          }
        ],
        "tags": {
          "add": [
            {
              "id": "123"
            }
          ],
          "remove": [
            {
              "id": "987"
            }
          ]
        }
      }
    ]
  }'

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:"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 most recent task completed as a Unix timestamp. Set as soon as any task completes, so check state to know whether the whole job has finished. Null until a task completes.

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