# What removing a domain would do with its DNS records

> What removing a domain would do with its DNS records: CustomDomain™ API reference in the connections group. Covers parameters, request body and responses.

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

## `GET https://api.customdomain.ai/v1/connections/{id}/removal`

Read-only. Lists the records we added, what each one did to its name when we wrote it (created, added to a shared set, replaced, merged) and what it held before when we know, what a removal would do with each, whether that can happen automatically, needs one more sign-in or key, or only by hand, and the exact manual steps. Show it before asking the person to confirm. While a removal runs, `removal_started_at` is set. Once the domain is removed, it answers `removed: true` with `result`, what the removal did, to the callers that could have removed it: read this, not the connection's `404`, to learn the outcome. An end user's widget token must be bound as for `DELETE /connections/{id}`.

### Authentication

`widgetJWT`, `apiKey`

### Parameters

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

### Responses

| Status | Description |
| --- | --- |
| `200` | The removal plan, or the outcome of a finished removal |
| `401` | Error envelope: {code, title, details}. |
| `403` | Error envelope: {code, title, details}. |
| `404` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_id` | string | yes |  |
| `domain` | string | yes |  |
| `provider` | string | no |  |
| `provider_name` | string | no |  |
| `connected_via` | string | yes | The rail that wrote the records (see `Connection.write_rail`), `manual` when none did, or `unknown_api` for an older connection written through a provider API. |
| `access` | `kept`, `one_time`, `none` | yes | What access we hold now. |
| `access_detail` | string | no |  |
| `record_removal` | `automatic`, `partial`, `reauthorize`, `manual`, `in_use`, `not_needed` | yes | What choosing `remove` can do: `automatic` with the access we kept; `partial` (some automatically, the rest by hand: a Domain Connect revert cannot restore a replaced value, and the Route 53 access role cannot delete); `reauthorize` (one more sign-in or key, see `reauthorize`); `manual` (only by hand, see `manual_steps`); `in_use` (another connection still serves the domain, so the records stay); `not_needed` (nothing was added). |
| `default_choice` | `remove`, `keep` | yes | The choice to offer first: `remove` when it can run without the person (automatic or partial), `keep` otherwise. A `DELETE` without a records choice keeps its original behaviour instead (see `DELETE /connections/{id}`). |
| `reauthorize` | object | no |  |
| `records_in_use_elsewhere` | boolean | yes |  |
| `records` | array of object | yes |  |
| `manual_steps` | array of string | yes | The exact steps to remove the records by hand, in order. |
| `notes` | array of string | no |  |
| `teardown` | array of string | yes | What always happens, whatever the choice. |
| `removal_started_at` | string | no | Set while a removal of the domain is running. |
| `removed` | boolean | no | True once the domain is removed: the connection is gone and `result` is what the removal did with its records. |
| `removed_at` | string | no |  |
| `result` | object | no |  |

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