# Create and Manage Secondary Zones

{% hint style="info" %}
**Prerequisite:** Before creating a secondary zone with IONOS Cloud DNS, ensure that the primary zone is capable of establishing a zone transfer with the secondary DNS server; this means port 53 is open for TCP and UDP connections.
{% endhint %}

To create a secondary zone on the IONOS Cloud DNS, follow this step:

* Perform a POST request to the `/secondaryzones` endpoint by providing the `zoneName`, `description`, and `primaryIps` for the IP address of the primary nameserver.

{% hint style="info" %}
**Note:** For sending DNS notify messages, Cloud DNS uses following Anycast addresses: IPv4 212.227.123.25 or IPv6 2001:8d8:fe:53::5cd:25.
{% endhint %}

{% hint style="success" %}
**Result:** On a successful POST request, you receive a response containing the secondary zone UUID, Name Servers, primaryIps, and the request status.
{% endhint %}

### Request

```bash
curl --location 'https://dns.de-fra.ionos.com/secondaryzones' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO' \
--data '{
    "properties": {
        "zoneName": "example.com",
        "description": "This is a secondary zone created in IONOS Cloud DNS",
        "primaryIps": [
            "192.0.2.2",
            "192.0.2.3"
        ]
    }
}'
```

### Response

**202 Accepted**

```bash
{
    "id": "a1bc82de-4cc5-40ca-bfb3-4e93bd9a367c",
    "type": "secondaryzone",
    "href": "<RESOURCE-URI>",
    "metadata": {
        "createdDate": "2023-08-04T10:21:32+00:00",
        "lastModifiedDate": "2023-08-04T10:21:33+00:00",
        "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
        "nameservers": [
            "nscs.ui-dns.com",
            "nscs.ui-dns.de",
            "nscs.ui-dns.org",
            "nscs.ui-dns.biz"
        ],
        "state": "AVAILABLE"
    },
    "properties": {
        "description": "This is a secondary zone created in IONOS Cloud DNS",
        "primaryIps": [
            "192.0.2.2",
            "192.0.2.3"
        ],
        "zoneName": "example.com"
    }
}
```

#### Response Fields

| Field                | Type   | Description                                 | Example                                                                                   |
| -------------------- | ------ | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **id**               | string | UUID of the secondary zone                  | a1bc82de-4cc5-40ca-bfb3-4e93bd9a367c                                                      |
| **createdDate**      | string | Secondary zone creation timestamp           | 2023-08-04T10:21:32+00:00                                                                 |
| **lastModifiedDate** | string | Secondary zone update timestamp             | 2023-08-04T10:21:33+00:00                                                                 |
| **resourceURN**      | string | Unique name of the resource                 | `ionos:<product>:<location>:<contract>:<resource-path>`                                   |
| **nameservers**      | array  | Name Servers assigned to the secondary zone | <p>"nscs.ui-dns.com",<br>"nscs.ui-dns.de",<br>"nscs.ui-dns.org",<br>"nscs.ui-dns.biz"</p> |
| **state**            | string | State of the secondary zone                 | AVAILABLE                                                                                 |
| **description**      | string | Description of the secondary zone           | This is a secondary zone created in IONOS Cloud DNS                                       |
| **primaryIps**       | array  | IP addresses of the primary nameserver      | <p>"192.0.2.2"<br>"192.0.2.3"</p>                                                         |
| **zoneName**         | string | Name of the secondary zone                  | example.com                                                                               |

## Retrieve all secondary zones

To retrieve information about all the secondary zones, follow this step:

* Send a GET request to the `/secondaryzones` endpoint.

{% hint style="success" %}
**Result:** On a successful GET request, you receive a response containing all secondary zones.
{% endhint %}

### Request

```bash
curl --location 'https://dns.de-fra.ionos.com/secondaryzones' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO'
```

### Response

**200 OK**

```bash
{
    "id": "0a85684c-2171-5a78-985a-a3999a0f5046",
    "type": "collection",
    "href": "<RESOURCE-URI>",
    "items": [
        {
            "id": "a1bc82de-4cc5-40ca-bfb3-4e93bd9a367c",
            "type": "secondaryzone",
            "href": "<RESOURCE-URI>",
            "metadata": {
                "createdDate": "2023-08-04T13:14:28+00:00",
                "lastModifiedDate": "2023-08-04T13:14:28+00:00",
                "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
                "nameservers": [
                    "nscs.ui-dns.com",
                    "nscs.ui-dns.de",
                    "nscs.ui-dns.org",
                    "nscs.ui-dns.biz"
                ],
                "state": "AVAILABLE"
            },
            "properties": {
                "description": "This is a secondary zone created in IONOS Cloud DNS",
                "primaryIps": [
                    "192.0.2.2",
                    "192.0.2.3"
                ],
                "zoneName": "example.com"
            }
        },
        {
            "id": "33085c93-425c-4909-9a5c-64ebf34dd9e9",
            "type": "secondaryzone",
            "href": "<RESOURCE-URI>",
            "metadata": {
                "createdDate": "2023-08-04T13:15:32+00:00",
                "lastModifiedDate": "2023-08-04T13:15:32+00:00",
                "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",                 
                "nameservers": [
                    "nscs.ui-dns.com",
                    "nscs.ui-dns.de",
                    "nscs.ui-dns.org",
                    "nscs.ui-dns.biz"
                ],
                "state": "AVAILABLE"
            },
            "properties": {
                "description": "This is a secondary zone created in IONOS Cloud DNS",
                "primaryIps": [
                    "192.0.2.2",
                    "192.0.2.3"
                ],
                "zoneName": "example.info"
            }
        },
        {
            "id": "fa4e179a-b1ab-4de5-ae38-48d5f02a605f",
            "type": "secondaryzone",
            "href": "<RESOURCE-URI>",
            "metadata": {
                "createdDate": "2023-08-04T13:15:40+00:00",
                "lastModifiedDate": "2023-08-04T13:15:40+00:00",
                "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",               
                "nameservers": [
                    "nscs.ui-dns.com",
                    "nscs.ui-dns.de",
                    "nscs.ui-dns.org",
                    "nscs.ui-dns.biz"
                ],                 
                "state": "AVAILABLE"
            },
            "properties": {
                "description": "This is a secondary zone created in IONOS Cloud DNS",
                "primaryIps": [
                    "192.0.2.2",
                    "192.0.2.3"
                ],
                "zoneName": "example.net"
            }
        },
        {
            "id": "04706207-a691-4710-902d-10acf5441bf1",
            "type": "secondaryzone",
            "href": "<RESOURCE-URI>",
            "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
            "metadata": {
                "createdDate": "2023-08-04T13:15:46+00:00",
                "lastModifiedDate": "2023-08-04T13:15:46+00:00",               
                "nameservers": [
                    "nscs.ui-dns.com",
                    "nscs.ui-dns.de",
                    "nscs.ui-dns.org",
                    "nscs.ui-dns.biz"
                ],                 
                "state": "AVAILABLE"
            },
            "properties": {
                "description": "This is a secondary zone created in IONOS Cloud DNS",
                "primaryIps": [
                    "192.0.2.2",
                    "192.0.2.3"
                ],
                "zoneName": "example.org"
            }
        }
    ],
    "offset": 0,
    "limit": 100,
    "_links": {
        "self": "http://THIS-PAGE-URI",
        "next": "http://NEXT-PAGE-URI"
    }
}
```

### Response Fields

| Field                | Type   | Description                                 | Example                                                                                   |
| -------------------- | ------ | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **id**               | string | UUID of the secondary zone                  | 04706207-a691-4710-902d-10acf5441bf1                                                      |
| **createdDate**      | string | Secondary zone creation timestamp           | 2023-08-04T13:15:46+00:00                                                                 |
| **lastModifiedDate** | string | Secondary zone update timestamp             | 2023-08-04T13:15:46+00:00                                                                 |
| **resourceURN**      | string | Unique name of the resource                 | `ionos:<product>:<location>:<contract>:<resource-path>`                                   |
| **nameservers**      | array  | Name Servers assigned to the secondary zone | <p>"nscs.ui-dns.com",<br>"nscs.ui-dns.de",<br>"nscs.ui-dns.org",<br>"nscs.ui-dns.biz"</p> |
| **state**            | string | State of the secondary zone                 | AVAILABLE                                                                                 |
| **description**      | string | Description of the secondary zone           | This is a secondary zone created in IONOS Cloud DNS                                       |
| **primaryIps**       | array  | IP addresses of the primary nameserver      | <p>"192.0.2.2"<br>"192.0.2.3"</p>                                                         |
| **zoneName**         | string | Name of the secondary zone                  | example.org                                                                               |

## Retrieve a specific secondary zone information

To retrieve information about a specific secondary zone, follow this step:

* Send a GET request to the `/secondaryzones/{secondaryzoneId}` endpoint.

{% hint style="success" %}
**Result:** On a successful GET request, you receive a response containing the secondary zone UUID, Name Servers, primaryIps, and secondary zone status.
{% endhint %}

### Request

```bash
curl --location 'https://dns.de-fra.ionos.com/secondaryzones/04706207-a691-4710-902d-10acf5441bf1' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO'
```

### Response

```bash
{
    "id": "04706207-a691-4710-902d-10acf5441bf1",
    "type": "secondaryzone",
    "href": "<RESOURCE-URI>",
    "metadata": {
        "createdDate": "2023-08-04T13:15:46+00:00",
        "lastModifiedDate": "2023-08-04T13:15:46+00:00",
        "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
        "nameservers": [
            "nscs.ui-dns.com",
            "nscs.ui-dns.de",
            "nscs.ui-dns.org",
            "nscs.ui-dns.biz"
        ],
        "state": "AVAILABLE"
    },
    "properties": {
        "description": "This is a secondary zone created in IONOS Cloud DNS",
        "primaryIps": [
            "192.0.2.2",
            "192.0.2.3"
        ],
        "zoneName": "example.org"
    }
}
```

#### Response Fields

| Field                | Type   | Description                                 | Example                                                                                   |
| -------------------- | ------ | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **id**               | string | UUID of the secondary zone                  | 04706207-a691-4710-902d-10acf5441bf1                                                      |
| **resourceURN**      | string | Unique name of the resource                 | `ionos:<product>:<location>:<contract>:<resource-path>`                                   |
| **createdDate**      | string | Secondary zone creation timestamp           | 2023-08-04T13:15:46+00:00                                                                 |
| **lastModifiedDate** | string | Secondary zone update timestamp             | 2023-08-04T13:15:46+00:00                                                                 |
| **nameservers**      | array  | Name Servers assigned to the secondary zone | <p>"nscs.ui-dns.com",<br>"nscs.ui-dns.de",<br>"nscs.ui-dns.org",<br>"nscs.ui-dns.biz"</p> |
| **state**            | string | State of the secondary zone                 | AVAILABLE                                                                                 |
| **description**      | string | Description of the secondary zone           | This is a secondary zone created in IONOS Cloud DNS                                       |
| **primaryIps**       | array  | IP addresses of the primary nameserver      | <p>"192.0.2.2"<br>"192.0.2.3"</p>                                                         |
| **zoneName**         | string | Name of the secondary zone                  | example.org                                                                               |

## Retrieve records for a specific secondary zone information

To retrieve records information about a specific secondary zone, follow this step:

* Send a GET request to the `/secondaryzones/{secondaryzoneId}/records` endpoint.

{% hint style="success" %}
**Result:** On a successful GET request, you receive a response containing the secondary zone records information: status,content, type, priority, TTL and name.
{% endhint %}

### Request

```bash
curl --location 'https://dns.de-fra.ionos.com/secondaryzones/04706207-a691-4710-902d-10acf5441bf1/records' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO'
```

### Response

```bash
{
    "id": "04706207-a691-4710-902d-10acf5441bf1",
    "type": "collection",
    "href": "<RESOURCE-URI>",
    "metadata": {
        "primaryIps": [
            "192.0.2.2"
        ]
    },
    "items": [
        {
            "type": "record",
            "metadata": {
                "fqdn": "example.org",
                "zoneId": "04706207-a691-4710-902d-10acf5441bf1",
                "rootName": "example.org"
            },
            "properties": {
                "content": "example.org hostmaster.example.org 2037070192 28800 7200 604800 600",
                "enabled": true,
                "name": "",
                "priority": 0,
                "ttl": 3600,
                "type": "SOA"
            }
        },
        {
            "type": "record",
            "metadata": {
                "fqdn": "example.org",
                "zoneId": "04706207-a691-4710-902d-10acf5441bf1",
                "rootName": "example.org"
            },
            "properties": {
                "content": "ns.ui-global-dns.de",
                "enabled": true,
                "name": "",
                "priority": 0,
                "ttl": 3600,
                "type": "NS"
            }
        },
        {
            "type": "record",
            "metadata": {
                "fqdn": "example.org",
                "zoneId": "04706207-a691-4710-902d-10acf5441bf1",
                "rootName": "example.org"
            },
            "properties": {
                "content": "ns.ui-global-dns.biz",
                "enabled": true,
                "name": "",
                "priority": 0,
                "ttl": 3600,
                "type": "NS"
            }
        },
        {
            "type": "record",
            "metadata": {
                "fqdn": "example.org",
                "zoneId": "04706207-a691-4710-902d-10acf5441bf1",
                "rootName": "example.org"
            },
            "properties": {
                "content": "ns.ui-global-dns.com",
                "enabled": true,
                "name": "",
                "priority": 0,
                "ttl": 3600,
                "type": "NS"
            }
        },
        {
            "type": "record",
            "metadata": {
                "fqdn": "example.org",
                "zoneId": "04706207-a691-4710-902d-10acf5441bf1",
                "rootName": "example.org"
            },
            "properties": {
                "content": "ns.ui-global-dns.org",
                "enabled": true,
                "name": "",
                "priority": 0,
                "ttl": 3600,
                "type": "NS"
            }
        },
        {
            "type": "record",
            "metadata": {
                "fqdn": "www.example.org",
                "zoneId": "04706207-a691-4710-902d-10acf5441bf1",
                "rootName": "example.org"
            },
            "properties": {
                "content": "192.0.2.3",
                "enabled": true,
                "name": "www",
                "priority": 0,
                "ttl": 3600,
                "type": "A"
            }
        },
        {
            "type": "record",
            "metadata": {
                "fqdn": "www.example.org",
                "zoneId": "04706207-a691-4710-902d-10acf5441bf1",
                "rootName": "example.org"
            },
            "properties": {
                "content": "2001:0db8::1",
                "enabled": true,
                "name": "www",
                "priority": 0,
                "ttl": 3600,
                "type": "AAAA"
            }
        },
        {
            "type": "record",
            "metadata": {
                "fqdn": "www2.example.org",
                "zoneId": "04706207-a691-4710-902d-10acf5441bf1",
                "rootName": "example.org"
            },
            "properties": {
                "content": "203.0.113.220",
                "enabled": true,
                "name": "www2",
                "priority": 0,
                "ttl": 3600,
                "type": "A"
            }
        }
    ],
    "offset": 0,
    "limit": 100,
    "_links": {
        "self": "http://THIS-PAGE-URI",
        "next": "http://NEXT-PAGE-URI"
    }
}
```

#### Response Fields

| Field           | Type    | Description                                                                 | Example                                                             |
| --------------- | ------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **id**          | string  | UUID of the secondary zone                                                  | 04706207-a691-4710-902d-10acf5441bf1                                |
| **description** | string  | Description of the secondary zone                                           | This is a secondary zone created in IONOS Cloud DNS                 |
| **primaryIps**  | array   | IP addresses of the primary nameserver                                      | 192.0.2.2                                                           |
| **zoneName**    | string  | Name of the secondary zone                                                  | example.org                                                         |
| **fqdn**        | string  | Fully qualified domain name resulting from the record name and the zoneName | example.org                                                         |
| **rootName**    | string  | Root name of the secondary zone                                             | example.org                                                         |
| **content**     | string  | Content of the secondary zone                                               | example.org hostmaster.example.org 2037070192 28800 7200 604800 600 |
| **enabled**     | boolean | Status of the secondary zone                                                | true                                                                |
| **name**        | string  | Name of the secondary zone                                                  | www                                                                 |
| **priority**    | integer | Priority of the secondary zone                                              | 0                                                                   |
| **ttl**         | integer | TTL of the secondary zone                                                   | 3600                                                                |
| **type**        | string  | Type of a record in the secondary zone                                      | SOA                                                                 |

## Modify secondary zone

To modify the description of a secondary zone or update the IP addresses of its primary nameserver, follow this step:

* Send a PUT request to the `/secondaryzones/{secondaryzoneId}` endpoint.

{% hint style="success" %}
**Result:** On a successful PUT request, you receive a response containing the secondary zone metadata with the new updated properties.
{% endhint %}

### Request

```bash

curl --location --request PUT 'https://dns.de-fra.ionos.com/secondaryzones/04706207-a691-4710-902d-10acf5441bf1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO' \
--data '{
    "properties": {
        "zoneName": "example.org",
        "description": "Changing description and primaryIps for secondary zone example.org",
        "primaryIps": [
            "192.0.2.2",
            "192.0.2.4"
        ]
    }
}'
```

### Response

**202 Accepted**

```bash
{
    "id": "a1bc82de-4cc5-40ca-bfb3-4e93bd9a367c",
    "type": "secondaryzone",
    "href": "<RESOURCE-URI>",
    "metadata": {
        "createdDate": "2023-08-04T10:21:32+00:00",
        "lastModifiedDate": "2023-08-10T09:32:29+00:00",
        "resourceURN": "ionos:<product>:<location>:<contract>:<resource-path>",
        "nameservers": [
            "nscs.ui-dns.com",
            "nscs.ui-dns.de",
            "nscs.ui-dns.org",
            "nscs.ui-dns.biz"
        ],
        "state": "AVAILABLE"
    },
    "properties": {
        "description": "Changing description and primaryIps for secondary zone example.com",
        "primaryIps": [
            "192.0.2.2",
            "192.0.2.4"
        ],
        "zoneName": "example.com"
    }
}
```

#### Response Fields

| Field                | Type   | Description                                 | Example                                                                                   |
| -------------------- | ------ | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **id**               | string | UUID of the secondary zone                  | a1bc82de-4cc5-40ca-bfb3-4e93bd9a367c                                                      |
| **createdDate**      | string | Secondary zone creation timestamp           | 2023-08-04T10:21:32+00:00                                                                 |
| **lastModifiedDate** | string | Secondary zone update timestamp             | 2023-08-10T09:32:29+00:00                                                                 |
| **resourceURN**      | string | Unique name of the resource                 | `ionos:<product>:<location>:<contract>:<resource-path>`                                   |
| **nameservers**      | array  | Name Servers assigned to the secondary zone | <p>"nscs.ui-dns.com",<br>"nscs.ui-dns.de",<br>"nscs.ui-dns.org",<br>"nscs.ui-dns.biz"</p> |
| **state**            | string | State of the request                        | AVAILABLE                                                                                 |
| **description**      | string | Description of the secondary zone           | Changing description and primaryIps for secondary zone example.com                        |
| **primaryIps**       | array  | IP addresses of the primary nameserver      | 192.0.2.2, < /br> 192.0.2.4                                                               |
| **zoneName**         | string | Name of the secondary zone                  | example.com                                                                               |

## Initiate zone transfer to a secondary zone

{% hint style="info" %}
**Note:** The creation of a secondary zone initiates zone transfer. In case of disrupted network connectivity at this time, you can initiate the zone transfer manually between the primary and secondary (i.e. secondary name server could not access primary nameserver on port 53) zones.
{% endhint %}

To initiate zone transfer from the primary zone to the secondary zone, follow this step:

* Send a PUT request to the `/secondaryzones/{secondaryzoneId}/axfr` endpoint.

{% hint style="info" %}
**Note:** For sending DNS notify messages, Cloud DNS uses following Anycast addresses: IPv4 212.227.123.25 or IPv6 2001:8d8:fe:53::5cd:25.
{% endhint %}

{% hint style="success" %}
**Result:** On a successful PUT request, you receive an HTTP response 200 OK.
{% endhint %}

### Request

```bash
curl --location --request PUT 'https://dns.de-fra.ionos.com/secondaryzones/a1bc82de-4cc5-40ca-bfb3-4e93bd9a367c/axfr' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO'
```

### Response

**200 OK**

## Check zone transfer status

To check zone transfer status, follow this step:

* Perform a GET request to `/secondaryzones/{secondaryzoneId}/axfr` endpoint.

{% hint style="success" %}
**Result:** On a successful GET request, you receive a response for AXFR communication status for each of primaryIps.
{% endhint %}

### Request

```bash
curl --location 'https://dns.de-fra.ionos.com/secondaryzones/a1bc82de-4cc5-40ca-bfb3-4e93bd9a367c/axfr' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO'
```

### Response

**200 OK**

```bash
{
    "items": [
        {
            "errorMessage": "",
            "primaryIp": "192.0.2.2",
            "status": "OK"
        }
    ],
    "type": "collection"
}
```

#### Response Fields

| Field            | Type   | Description               | Example   |
| ---------------- | ------ | ------------------------- | --------- |
| **errorMessage** | string | Error message if any      |           |
| **primaryIp**    | string | Primary IP address        | 192.0.2.2 |
| **status**       | string | AXFR communication status | OK        |

## Delete a secondary zone

To delete a secondary zone from the IONOS Cloud DNS, follow this step:

* Send a DELETE request to the `/secondaryzones/{zoneId}` endpoint.

{% hint style="success" %}
**Result:** On a successful DELETE request, you receive an HTTP status 200 Accepted.
{% endhint %}

### Request

```bash
curl --location --request DELETE 'https://dns.de-fra.ionos.com/secondaryzones/d8ff66f6-6777-42a8-b363-7f80b9105db4' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO'
```

### Response

**200 Accepted**

## Quota

To retrieve the quota of secondary zones, perform a GET request to the `/quota` endpoint.

{% hint style="success" %}
**Result:** On a successful GET request, you receive a response containing the quota limits and quota usage for your contract.
{% endhint %}

### Request

```bash
curl --location 'https://dns.de-fra.ionos.com/quota' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJraWQiO' \
--header 'Content-Type: application/json'
```

### Response

**200 OK**

```json
{
  "quotaLimits": {
    "records": 100000,
    "reverseRecords": 5000,
    "secondaryZones": 100000,
    "zones": 50000
  },
  "quotaUsage": {
    "records": 9,
    "reverseRecords": 1,
    "secondaryZones": 6,
    "zones": 5
  }
}
```

#### Response Fields

| Field              | Type   | Description                        | Example |
| ------------------ | ------ | ---------------------------------- | ------- |
| **records**        | string | Number of DNS records              | 100000  |
| **reverseRecords** | string | Number of reverse DNS records      | 5000    |
| **secondaryZones** | string | Number of secondary zones          | 100000  |
| **zones**          | string | Number of primary zones            | 50000   |
| **records**        | string | Number of DNS records used         | 9       |
| **reverseRecords** | string | Number of reverse DNS records used | 1       |
| **secondaryZones** | string | Number of secondary zones used     | 6       |
| **zones**          | string | Number of primary zones used       | 5       |