# Import a zone file or add records to the managed zone

> Import a zone file or add records to the managed zone: CustomDomain™ API reference in the managed dns group. Covers parameters, request body and responses.

Source: https://docs.customdomain.ai/docs/api-reference/managed-dns/addManagedDNSRecords

## `POST https://api.customdomain.ai/v1/connections/{id}/managed-dns/records`

Send exactly one of `zone_file` (a BIND zone file, at most 256 KB) or `records` (at most 500). Records from a zone file are `imported`: for every name and type the file defines, they replace what discovery found. Listed records are `manual` and are added alongside what is there. Records CustomDomain™ needs for the connection always win: an imported record that collides with one is skipped with a note, and a listed one is refused with 409. Zone file lines that can't be hosted (SOA, the zone's own NS set, unsupported types, names outside the zone) are skipped, each with a warning naming its line. A zone holds at most 500 records.

Once the zone is `active`, only an API key or an app-scoped widget token may change it; an end user's connect-scoped token may change the zone only during setup, and only a zone that is its own: its connection's end user and every connection linked to the zone are the token's (as for the start above).

### Authentication

`apiKey`, `widgetJWT`

### Parameters

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

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `zone_file` | string | no | A BIND zone file (RFC 1035 master format). |
| `records` | array of object | no |  |

### Responses

| Status | Description |
| --- | --- |
| `200` | The zone after the change. |
| `400` | Error envelope: {code, title, details}. |
| `401` | Error envelope: {code, title, details}. |
| `403` | `token_wrong_end_user` (a widget token whose end user is not the connection's), or `forbidden` (the zone is live and the token is an end user's: use an API key or an app-scoped token). |
| `404` | Error envelope: {code, title, details}. |
| `409` | A listed record would override one CustomDomain™ needs for the connection, or (a widget token) the zone is hosted for someone else because not every connection linked to it is the token's. |
| `413` | Error envelope: {code, title, details}. |
| `422` | `invalid_zone_file` (nothing in the file can be hosted) or `too_many_records` (the zone would pass 500 records). |
| `503` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `zone` | string | yes | The hosted zone: the registrable domain. |
| `status` | `awaiting_delegation`, `active`, `failed` | yes | `awaiting_delegation`: the zone holds the records; set the nameservers below at the registrar. `active`: every nameserver the registry lists is ours. `failed`: the switch never happened within 14 days, or the nameservers moved away again (the first warning says which); a failed zone keeps being checked and turns active once the delegation appears. |
| `nameservers` | array of string | yes | The nameservers to set at the registrar. |
| `observed_nameservers` | array of string | yes | The nameservers the registry listed at the last check. |
| `registrar` | object | yes | The domain's registrar, or null when unknown. |
| `records` | array of object | yes |  |
| `warnings` | array of string | yes | Plain-language notes for the user (a partial delegation, records a zone file import skipped, records replaced). |
| `checked_at` | string | yes | When the delegation was last checked. |
| `activated_at` | string or null | yes |  |

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