Intercom API (unofficial showcase)
POST/contacts/bulk

Bulk create contacts

Creates contacts in bulk using an asynchronous job; this is a strict create operation and does not update existing contacts. Supply up to 100 contact objects in contacts; items that match an existing contact by external_id or email are rejected while other items can still be created. Use the returned job ID with GET /contacts/bulk/{id} to check progress and identify whether items were rejected.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

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 creation 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 create. 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 the 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 use email_verified together with email; each item in companies must include company_id, and only the fields defined for contact objects are accepted.