# Connect domains with the account

> Connect domains with the account: CustomDomain™ API reference in the provider accounts group. Covers parameters, request body, responses and error codes.

Source: https://docs.customdomain.ai/docs/api-reference/provider-accounts/connectWithProviderAccount

## `POST https://api.customdomain.ai/v1/provider-accounts/{id}/connect`

Creates a connection for each domain under its application and writes its records with the account's key (keeping the CAA and TXT values already there and recording what each write replaced).

A domain goes into the application named for it, else the call's `application_id`, else the application that already holds it in the workspace (its own connection's, so a domain the workspace already serves is linked where it lives). A domain none of those names answers `400`, and so does one two applications hold; so does a domain named for two different applications. A call takes at most 200 domains (a domain named twice is one; `400` beyond). Every application used must be the workspace's (`404` otherwise) and one the key serves, and every domain must be inside the key's scope: a call that is refused for any of this changes nothing, because all of it is checked before the first write. Each domain is linked to the account once its records are written; a domain whose write fails is not linked and keeps the access it had. A continuous account then keeps the linked domains in sync. A domain the application already serves is only linked (`provider_account.relinked` in the audit log), and only to a key at the provider its DNS is at whose scope already holds it; any other such domain is answered `already` with the reason and left as it is. A one time account deletes its key once the domains are connected, even when the caller has gone away by then, and past its hour answers `409`. A domain in a zone the key does not reach fails alone (`zone_not_reached` on the connection); the account is flagged `needs_reconnect` only when the provider refuses the key itself, which is checked with a request that does not depend on the zone. A key made at a secure sign in serves its own application and the applications an admin shared it with (`application_ids`); naming any other application's id answers `403` (this key is not shared with this application; an admin or an owner can share it). A domain outside the key's scope answers `400`, naming the domains, except for a key a member of the workspace made at a sign in started in the console (the console's signed call, not an API key that names the console): when a read of the domain's zone with the key works, the domain is connected with no new sign in, and the zone is added to the key's scope once a write there works (`provider_account.domain_added` in the audit log). A zone the key does not reach answers `422` `zone_not_reached`, naming the domains, and a provider that cannot say (a timeout, a `5xx`) answers `503`, never a refusal of the key: the same two answers `PATCH /provider-accounts/{id}` gives, with nothing written. A call reads at most 20 such zones, one read for each, and answers `400` `too_many_domains_to_check` before the first read beyond that; those reads are taken from the workspace's hourly budget of reach checks, and a call whose reads do not fit in what is left answers `429` `reach_quota` with `Retry-After`, with nothing read or written; `PATCH /provider-accounts/{id}` is the other way to widen a scope. A key an end user's secure sign-in made in the widget, or one a sign in started through the API made, answers `403`: it connects domains only through that end user's own widget session. A domain the application already has, kept by such a key, is left as it is (`already`, not re-linked). Takes an admin, an owner or the member who connected the account. A call that connected at least one domain (its records written with the key, or a domain already serving now linked to the account) is recorded in the audit log as one `provider_account.domains_connected` row naming those domains, by name only, beside the `provider_account.relinked` and `provider_account.domain_added` rows it may also write; a call that connected none writes no such row. A domain already serving that was linked to this account before the call is left as it is (`already`), is not named in the row, and does not make one.

### Authentication

`apiKey`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `application_id` | string | no | The application for a domain that names none of its own. Leave it out when every domain names its own or is already held by an application of the workspace: that application is the default. |
| `domains` | array of object | yes | The domains to connect, at most 200. Each is a name, or an object naming the application that one domain goes into. |
| `www_redirect` | boolean | no |  |
| `client_label` | string | no | The name of the client every domain of this call is for, as `POST /connections:bulk` takes it (a name with nothing readable left stores no name). A domain the application already has keeps its own name. |

### Responses

| Status | Description |
| --- | --- |
| `200` | Per domain results and the account |
| `400` | Error envelope: {code, title, details}. |
| `401` | Error envelope: {code, title, details}. |
| `403` | Error envelope: {code, title, details}. |
| `404` | Error envelope: {code, title, details}. |
| `409` | Error envelope: {code, title, details}. |
| `422` | Error envelope: {code, title, details}. |
| `429` | `reach_quota`: the workspace has made as many reads at DNS providers, to find out what a key reaches, as it may this hour (the saved key resolver's reads, a key's reach check when its scope is widened, the list of a key's domains and Check now share one budget). Nothing was read at the provider, nothing changed and nothing was spent from the hour. `Retry-After` is the seconds until the hour ends, when the count starts again. |
| `503` | Error envelope: {code, title, details}. |

### `200` response body

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

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