Bulk create contacts

Request

You can bulk create contacts by submitting an array of contact objects. This is a strict create and never updates an existing contact.

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

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

Handling existing contacts

If a contact already exists with the given external_id or email (including an archived contact), that item is rejected and the job's state ends as completed_with_errors. New contacts in the same request are still created. The job state from GET /contacts/bulk/{id} is the signal that one or more items were rejected.

Created contacts aren't returned with IDs in the response. Look them up afterwards with Get a contact by External ID or Search contacts.

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.

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

contactsArray of objects, <= 100 itemsrequired

An array of contact objects to create. Maximum 100 contacts per request.

jobobject

Optional. Include to append tasks to an existing job.

curl -i -X POST \
  https://api.intercom.io/contacts/bulk \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "contacts": [
      {
        "external_id": "abc123",
        "email": "joe@bloggs.com",
        "name": "Joe Bloggs",
        "role": "user",
        "phone": "+353871234567",
        "avatar": "https://www.example.com/avatar_image.jpg",
        "signed_up_at": 1571672154,
        "last_seen_at": 1571672154,
        "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"
            }
          ]
        }
      }
    ]
  }'

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:"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/contacts/bulk/job_v2_1"

Response

{
  "id": "job_v2_2",
  "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_2"
}