# Forwarding

> Redirect a domain to another URL without running a web server, read the forward back, and remove it.

Forwarding points a domain at another URL without you running a web server. We take over the domain's DNS to do it.

:::danger[Forwarding replaces the domain's name servers]
Creating a forward switches the domain to our name servers and publishes the records needed to redirect it. **Any DNS you were running elsewhere stops being authoritative** — mail included. Deleting the forward restores the previous name servers.

If the domain has mail on it, do not use forwarding. Point the web records where you want them with the [zones API](https://www.domainnameapi.com/docs/dns-records/) instead and leave the MX records alone.
:::

## POST /api/v1/domains/forwards

Creates a forwarding record.

**Request**

```jsonc
{
  "domainName": "apiname.com",
  "redirectAddress": "https://www.apiname.net/landing",
  "forwardType": "Standard"
}
```

| Field | Required | Notes |
| --- | --- | --- |
| `domainName` | required | No underscores; no label may start or end with a hyphen. |
| `redirectAddress` | required | Destination URL. Maximum 100 characters. |
| `forwardType` | required | `Standard` or `Frame`. Case-insensitive, and the initial letter alone is enough — see below. |

| Value | Name | Behaviour |
| --- | --- | --- |
| 1 | `Standard` | HTTP 301 permanent redirect. The browser address bar shows the destination. Correct for almost all cases, and SEO-friendly. |
| 2 | `Frame` | The destination is loaded inside a frame, so the address bar keeps showing your domain. Breaks on sites that refuse framing, and is bad for SEO. Use only when the customer specifically asks for URL masking. |

### How `forwardType` is interpreted

The same relaxed matching as [`contactType`](https://www.domainnameapi.com/docs/domains/register/#how-contacttype-is-interpreted): the numeric value first, then the initial letter, case-insensitive.

| You send | Resolves to |
| --- | --- |
| `"Standard"`, `"standard"`, `"STANDARD"`, `"s"`, `"S"` | Standard |
| `"1"` | Standard |
| `"Frame"`, `"frame"`, `"FRAME"`, `"f"`, `"F"` | Frame |
| `"2"` | Frame |
| anything else | **rejected** with `Dna.DomainService:Domain:1018` |

:::note[One deliberate difference from `contactType`]
An unrecognised `contactType` silently falls back to `Registrant`. An unrecognised `forwardType` does **not** fall back — it is rejected. With only two options, silently picking the wrong one would set up the redirect in a way you did not ask for, so `"permanent"` or `"301"` give you a clear error rather than a surprise.
:::

**Response — 204, no body**

**Errors**

| Code | Meaning and fix |
| --- | --- |
| `DnaValidationError` | A required field is missing. |
| `Dna.DomainService:Domain:10005` | Invalid domain name, or it contains an underscore, or a label starts/ends with a hyphen. |
| `Dna.DomainService:Domain:1018` | `forwardType` could not be resolved to `Standard` or `Frame`. |
| `Dna.DomainService:Domain:1025` | A forward already exists. Delete it first, then create the new one. |
| `Dna.DomainService:Domain:1021` | Domain not yours. |
| `Dna.DomainService:DomainSale:10007` | The domain is listed for sale and uses parking records. Cancel the listing first. |

## GET /api/v1/domains/forwards · DELETE /api/v1/domains/forwards

Read or remove the forwarding record.

**GET — request and response**

```http
GET /api/v1/domains/forwards?domainName=apiname.com

{
  "redirectAlias": "https://www.apiname.net/landing",
  "redirectType": "Standard"
}
```

**DELETE — request**

```json
{
  "domainName": "apiname.com"
}
```

Returns 204. The name servers recorded before the forward was created are restored.

**Errors**

| Code | Meaning and fix |
| --- | --- |
| `Dna.DomainService:Domain:1017` | No forwarding configured on this domain. |
| `Dna.DomainService:Domain:1021` | Domain not yours. |