---
search:
  tags:
    - Contacts
    - POST
seo:
  description: >-
    Creates up to 1000 contacts in one request. Each item is a
    CreateContactRequest.… Reference for the POST /contacts/batch endpoint in
    the BillionSend API.
sidebar:
  label: Create contacts in bulk
  badge: POST
title: Create contacts in bulk
type: openapi-operation
---
Creates up to 1000 contacts in one request. Each item is a CreateContactRequest. `on_conflict` decides what happens to an email that already belongs to a contact — `error` (default), `skip`, or `upsert`. An upsert updates `first_name`/`last_name` only when provided, merges `properties` (provided keys overwrite), adds `segments` and upserts `topics`. `unsubscribed: true` opts the contact out; `unsubscribed: false` on an already unsubscribed contact is ignored — a batch never re-subscribes anyone, that stays an explicit PATCH /contacts/&#123;id&#125;. The `x-batch-validation` header picks strict (default, all-or-nothing) or permissive (valid subset written, failures listed in `errors`).

`POST /contacts/batch`

**Request body** (`application/json`, required)

Request body example:

```json
[
  {
    "email": "user@example.com",
    "first_name": "string",
    "last_name": "string",
    "unsubscribed": true,
    "properties": {
      "property1": null,
      "property2": null
    },
    "segments": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      }
    ],
    "topics": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "subscription": "opt_in"
      }
    ]
  }
]
```

**Responses**

- `200` — Batch processed
- `401` — Missing, malformed, unknown or revoked API key
- `403` — Plan limit reached (strict mode)
- `404` — Unknown segment or topic (strict mode)
- `409` — Contact already exists (strict mode, on\_conflict=error)
- `422` — Validation error
- `429` — Over the rate limit (rate\_limit\_exceeded, with Retry-After)

Response example, 200:

```json
{
  "data": [
    {
      "object": "contact",
      "index": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "status": "created"
    }
  ],
  "counts": {
    "created": 0,
    "updated": 0,
    "skipped": 0,
    "failed": 0
  },
  "errors": [
    {
      "index": 0,
      "statusCode": 0,
      "name": "string",
      "message": "string"
    }
  ]
}
```
