# Bulk update contacts

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.

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.

{% admonition type="info" name="Limits" %}
  - Maximum of 100 contacts per request.
  - You can append tasks to an existing job by including job.id in the request body.
{% /admonition %}

Endpoint: POST /contacts/bulk
Version: Preview
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)
    Intercom API version.By default, it's equal to the version set in the app package.
    Enum: "1.0", "1.1", "1.2", "1.3", "1.4", "2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13", "2.14", "Preview"

## Request fields (application/json):

  - `contacts` (array, required)
    An array of contact objects to update. Each must include an id and the fields to update. Maximum 100 contacts per request.

  - `contacts.id` (string, required)
    The unique identifier for the contact.
    Example: "abc123"

  - `contacts.email` (string)
    The contact's email address.
    Example: "joe@example.com"

  - `contacts.name` (string)
    The contact's name.
    Example: "Joe Bloggs"

  - `contacts.language_override` (string)
    A preferred language setting for the contact, used by the Intercom Messenger.
    Example: "fr"

  - `contacts.custom_attributes` (object)
    Custom attributes to update on the contact.

  - `job` (object)
    Optional. Include to append tasks to an existing job.

  - `job.id` (string)
    The ID of an existing bulk job to append to.
    Example: "job_v2_1"

## Response 202 fields (application/json):

  - `id` (string)
    The unique identifier for the bulk job.
    Example: "job_v2_1"

  - `type` (string)
    The type of the object.
    Enum: "contacts.bulk.job"

  - `state` (string)
    The current state of the job.
    Enum: "pending", "running", "completed", "completed_with_errors"

  - `created_at` (integer)
    The time the job was created as a UNIX timestamp.
    Example: 1713360000

  - `updated_at` (integer)
    The time the job was last updated as a UNIX timestamp.
    Example: 1713360060

  - `completed_at` (integer,null)
    The time the job completed as a UNIX timestamp. Null if not yet completed.
    Example: 1713360120

  - `tasks` (array)
    The tasks that make up this bulk job.

  - `tasks.id` (string)
    The unique identifier for the task.
    Example: "task_v2_1"

  - `tasks.item_count` (integer)
    The number of items in this task.
    Example: 3

  - `tasks.state` (string)
    The current state of the task.
    Enum: "pending", "running", "completed", "completed_with_errors"

  - `tasks.created_at` (integer)
    The time the task was created as a UNIX timestamp.
    Example: 1713360000

  - `tasks.started_at` (integer,null)
    The time the task started as a UNIX timestamp. Null if not yet started.
    Example: 1713360060

  - `tasks.completed_at` (integer,null)
    The time the task completed as a UNIX timestamp. Null if not yet completed.
    Example: 1713360120

  - `url` (string)
    The URL to check the job status.
    Example: "https://api.intercom.io/contacts/bulk/job_v2_1"

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: "error.list"

  - `request_id` (string,null)
    Example: "f93ecfa8-d08a-4325-8694-89aeb89c8f85"

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code
    Example: "unauthorized"

  - `errors.message` (string,null)
    Optional. Human readable description of the error.
    Example: "Access Token Invalid"

  - `errors.field` (string,null)
    Optional. Used to identify a particular field or query parameter that was in error.
    Example: "email"