Intercom API (unofficial showcase)
PUT/contacts/bulk

Bulk update contacts

Updates multiple contacts in an asynchronous job by applying the supplied fields to each identified contact. Include an id and the fields to change in each contact object, with no more than 100 objects in contacts. Use the returned job ID with GET /contacts/bulk/{id} to monitor progress; tag application is best-effort.

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 update 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 contact objects to update. Each must include an `id` and the fields to update. 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 contact item must include id; each item in companies must include company_id, and email_verified must be sent together with email.