---
title: "Update many contacts"
method: POST
path: "/contacts/bulk"
tags: ["Contacts"]
---

# Update many contacts

`POST /contacts/bulk`

## Request

- Base URL: `https://api.commonroom.io/api/v2`
- URL: `https://api.commonroom.io/api/v2/contacts/bulk`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/commonroom/apis/common-room-api-v2/docs/contacts/bulk/post.ts> (a function with typed inputs; its response is checked against the schema)

Apply the same change to up to 100 contacts in one request. The request must include at least one of segmentId, tagIdsToAdd, tagIdsToRemove, or customFields. Every ID, the segment, the tags, and the custom fields are validated before anything is written, and an error names every offending ID. Each change is idempotent: contacts already in the segment are skipped, so a request that fails part-way can be retried as a whole. Requires the `contacts:write` scope.

## Request body

- object
  - `contactIds` string[], required: Prefixed contact IDs (format `c_<number>`). Duplicates are ignored.
  - `segmentId` string: Add every contact to this segment (format `s_<number>`).
  - `tagIdsToAdd` string[]: Tag IDs (format `l_<number>`) to add to every record.
  - `tagIdsToRemove` string[]: Tag IDs (format `l_<number>`) to remove from every record.
  - `customFields` object[]: Custom-field values to set on every record in the request.
    - `customFieldId` string, required: Custom field ID (format `cf_<number>`)
    - `customFieldValue` union, required: A typed custom-field value. The `type` discriminator indicates the value's runtime type.
      - object
        - `type` 'string', required
        - `value` string, required
      - object
        - `type` 'url', required
        - `value` string, uri, required
      - object
        - `type` 'int', required
        - `value` integer, required
      - object
        - `type` 'number', required
        - `value` number, required
      - object
        - `type` 'date', required
        - `value` string, date-time, required
      - object
        - `type` 'boolean', required
        - `value` boolean, required

## Response `200`

The contacts were updated

- BulkUpdateResponse
  - `success` true, required
  - `data` object, required
    - `ids` string[], required: The prefixed IDs of the records that were updated, deduplicated.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: A contact, the segment, or a tag was not found
- `429`: Rate Limited

---

[API](https://skmtc.dev/commonroom/apis/common-room-api-v2.md) - [All operations](https://skmtc.dev/commonroom/apis/common-room-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/commonroom/apis/common-room-api-v2/revisions/865d4d43dadf?raw)