---
title: "Create contacts in bulk"
method: POST
path: "/contacts/bulk"
tags: ["contacts"]
---

# Create contacts in bulk

`POST /contacts/bulk`

Creates up to 1000 contacts in a single request. Each item is processed independently within its own database SAVEPOINT, so a failure on one row (e.g. missing email) does not stop the rest of the batch. The response returns a per-item status with either the created contact or an error message.

Returns 201 if at least one item was created. Returns 400 if the envelope is invalid (missing `contacts` array, empty array, more than 1000 items) or if every item failed.

## Request body

- ContactBulkCreateBody — Envelope for POST /contacts/bulk. Each element follows the same shape as ContactCreateBody.
  - `contacts` ContactCreateBody[], required — Contacts to create. Must contain between 1 and 1000 items.
    - `email` string, email, required
    - `first_name` string
    - `last_name` string
    - `source` string — Origin of the contact (e.g. 'hubspot', 'csv')
    - `can_email` boolean — Sets the contact's emailability. Applied whether this POST creates a new contact or matches an existing active contact by email. Defaults to true on creation when omitted.
    - `list_id` integer — Add the contact to this list immediately
    - `subscriptions` ContactCreateSubscriptionItem[] — Optional subscriptions to create for the contact. Each entry upserts a canonical subscription (no integration) on (contact_id, subscription_type_id): if one already exists its can_email is updated rather than a duplicate being inserted.
      - `subscription_type_id` integer, required
      - `can_email` boolean — Whether this subscription is emailable. Accepts 0/1 or true/false.
    - `options` object — Arbitrary key-value attributes stored on the contact. Persisted only when this POST creates a new contact; ignored when an active contact already exists for the email (same as first_name/last_name/source). Use PUT /contacts/{id} to merge options into an existing contact.
    - `system` string — External system name (e.g. 'hubspot'). Must be provided together with `identifier` to create an external identifier record.
    - `identifier` string — The contact's ID in the external system. Must be provided together with `system`.
    - `system_identifier` string — Optional sub-system identifier (e.g. a HubSpot portal ID).

## Response `201`

Bulk processed. Inspect per-item status in results.

## Other responses

- `400` — Invalid envelope, empty array, more than 1000 items, or all items failed
- `401` — Unauthorized

---

[API](https://skmtc.net/rasa/apis/rasa-io-api.md) · [All operations](https://skmtc.net/rasa/apis/rasa-io-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rasa/rasa-io-api/revisions/60891bc551db/schema)