# Create connections for a set of domains in one call

> Create connections for a set of domains in one call: CustomDomain™ API reference in the connections group. Covers parameters, request body and responses.

Source: https://docs.customdomain.ai/docs/api-reference/connections/bulkCreateConnections

## `POST https://api.customdomain.ai/v1/connections:bulk`

Fans out the same idempotent upsert as single-domain create. Each domain is independent: a bad domain is reported `failed` and the batch continues; a domain already connected under this app returns `already`. Max 200 domains per call.

Callable with an app scoped widget token or straight from your server with an API key, in which case the connections are created on the key's application, or on `application_id` when that names another application of the same tenant. A viewer's key is refused.

`client_label` names the client every connection the call creates is for, the way it does on a single create: an agency adds a client's domains together under the client's name, and the Domains page shows, filters and exports it. `PATCH /connections/{id}` changes it later. `end_user_ref` is your own id for the end user, set once and never changed. A domain that already exists keeps what it has and is reported `already`.

A workspace with no subscription yet connects its first ten domains, or the number an operator set, without one; the rest of a list are reported `failed` with the reason, one by one, until it starts its trial.

### Authentication

`widgetJWT`, `apiKey`

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domains` | array of string | yes |  |
| `batch_id` | string | no | correlates every domain connected in one session. |
| `end_user_ref` | string | no | Your own id for the customer these domains belong to. Stored on each connection this call creates and echoed back by the connection reads. Set once; it binds widget tokens to the connection, so it is not a name (send `client_label`). |
| `client_label` | string | no | The name of the client these domains are for, such as an agency's client. Trimmed to one line, at most 200 characters, with characters that draw nothing dropped; a name with nothing left stores no name. Stored on each connection this call creates; `PATCH /connections/{id}` changes it later. |
| `application_id` | string | no | API key callers only: create the connections on this application of the key's tenant instead of the key's own. A widget token may only name its own application. |

### Responses

| Status | Description |
| --- | --- |
| `200` | Per-domain results |
| `400` | Error envelope: {code, title, details}. |
| `401` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `results` | array of object | no |  |

The full specification is served at `GET https://api.customdomain.ai/v1/openapi.json`.