Zone Record API

Zone record attributes

Please refer to the definition of the ZoneRecord data type in our OpenAPI documentation.

Record Regions

The zone record regions is a feature that is only available to the Teams and Enterprise plans. If the feature is not enabled, you will receive an HTTP 412 response code.

Zone Record Regions lets you select geographical regions where you want a record to appear.

We currently have 8 points of presence:

Code Region
SV1 California, US
ORD Illinois, US
IAD Virginia, US
AMS Amsterdam, NL
TKO Tokyo, JP
SYD Sydney, AU
CDG Paris, FR
FRA Frankfurt, DE

When creating/updating a record, you can optionally select one or more regions. If you don’t select any, the record will appear in all of them (global).

List zone records

GET /:account/zones/:zone/records

Parameters

Name Type Description
:account integer The account id
:zone string The zone name

Filters

Name Description
:name_like Only include records containing given string
:name Only include records with name equal to given string
:type Only include records with record type equal to given string

Sorting

For general information about sorting, please refer to the main guide.

Name Description
id Sort records by ID
name Sort records by name (alphabetical order)
content Sort records by content
type Sort records by type

The default sorting policy is by ascending id.

Examples

List records for the zone example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records

List records for the zone example.com with TXT zone records, in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records?type=TXT

Response

Responds with HTTP 200 on success.

{
  "data": [
    {
      "id": 1,
      "zone_id": "example.com",
      "parent_id": null,
      "name": "",
      "content": "ns1.dnsimple.com admin.dnsimple.com 1458642070 86400 7200 604800 300",
      "ttl": 3600,
      "priority": null,
      "type": "SOA",
      "regions": [
        "global"
      ],
      "system_record": true,
      "created_at": "2016-03-22T10:20:53Z",
      "updated_at": "2016-10-05T09:26:38Z"
    },
    {
      "id": 69061,
      "zone_id": "example.com",
      "parent_id": null,
      "name": "",
      "content": "ns1.dnsimple.com",
      "ttl": 3600,
      "priority": null,
      "type": "NS",
      "regions": [
        "global"
      ],
      "system_record": true,
      "created_at": "2016-03-22T10:20:53Z",
      "updated_at": "2016-03-22T10:20:53Z"
    },
    {
      "id": 2,
      "zone_id": "example.com",
      "parent_id": null,
      "name": "",
      "content": "ns2.dnsimple.com",
      "ttl": 3600,
      "priority": null,
      "type": "NS",
      "regions": [
        "global"
      ],
      "system_record": true,
      "created_at": "2016-03-22T10:20:53Z",
      "updated_at": "2016-03-22T10:20:53Z"
    },
    {
      "id": 3,
      "zone_id": "example.com",
      "parent_id": null,
      "name": "",
      "content": "ns3.dnsimple.com",
      "ttl": 3600,
      "priority": null,
      "type": "NS",
      "regions": [
        "global"
      ],
      "system_record": true,
      "created_at": "2016-03-22T10:20:53Z",
      "updated_at": "2016-03-22T10:20:53Z"
    },
    {
      "id": 4,
      "zone_id": "example.com",
      "parent_id": null,
      "name": "",
      "content": "ns4.dnsimple.com",
      "ttl": 3600,
      "priority": null,
      "type": "NS",
      "regions": [
        "global"
      ],
      "system_record": true,
      "created_at": "2016-03-22T10:20:53Z",
      "updated_at": "2016-03-22T10:20:53Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 30,
    "total_entries": 5,
    "total_pages": 1
  }
}

Errors

Responds with HTTP 401 in case of case of authentication issues.

Create a zone record

POST /:account/zones/:zone/records

Parameters

Name Type Description
:account integer The account id
:zone string The zone name

Example

Create a record for the zone example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '<json>' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records

Input

Name Type Description
name string Required. The record name, without the domain. The domain will be automatically appended. Use an empty string to create a record for the apex.
type string Required.
content string Required.
ttl integer  
priority integer  
regions array Optional set of regions
integrated_zones array Optional set of IDs identifying the zones where the record should be created. If not specified, the record creation will be applied to the DNSimple zone and all integrated zones that support the record type. If specified, “dnsimple” must be included to create the record in the DNSimple zone.
Example
{
  "name": "",
  "type": "MX",
  "content": "mxa.example.com",
  "ttl": 600,
  "priority": 10,
  "regions": ["SV1", "IAD"],
  "integrated_zones": [1, 2, "dnsimple"]
}

Response

Responds with HTTP 201 on success.

{
  "data": {
    "id": 1,
    "zone_id": "example.com",
    "parent_id": null,
    "name": "www",
    "content": "127.0.0.1",
    "ttl": 600,
    "priority": null,
    "type": "A",
    "system_record": false,
    "regions": [
      "global"
    ],
    "created_at": "2016-01-07T17:45:13Z",
    "updated_at": "2016-01-07T17:45:13Z"
  }
}

Errors

Responds with HTTP 400 if the record cannot be created.

Responds with HTTP 401 in case of case of authentication issues.

Retrieve a zone record

GET /:account/zones/:zone/records/:record

Parameters

Name Type Description
:account integer The account id
:zone string The zone name
:record integer The record id

Example

Get the record 5 for the zone example.com, in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records/5

Response

Responds with HTTP 200 on success.

{
  "data": {
    "id": 5,
    "zone_id": "example.com",
    "parent_id": null,
    "name": "",
    "content": "mxa.example.com",
    "ttl": 600,
    "priority": 10,
    "type": "MX",
    "regions": [
      "SV1",
      "IAD"
    ],
    "system_record": false,
    "created_at": "2016-10-05T09:51:35Z",
    "updated_at": "2016-10-05T09:51:35Z"
  }
}

Errors

Responds with HTTP 401 in case of case of authentication issues.

Update a zone record

PATCH /:account/zones/:zone/records/:record

Parameters

Name Type Description
:account integer The account id
:zone string The zone name
:record integer The record id

Example

Update the record with ID 5 for zone example.com, in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X PATCH \
      -d '<json>' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records/5

Input

The following fields are updateable. You can pass zero or any of them.

Name Type Description
name string The record name, without the domain. The domain will be automatically appended. Use an empty string to create a record for the apex.
content string  
ttl integer  
priority integer  
regions array Optional set of regions
integrated_zones array Optional set of IDs identifying the zones where the record should be updated. If not specified, the record update will be applied to the DNSimple zone and all integrated zones that support the record type. If specified, “dnsimple” must be included to update the record in the DNSimple zone.
Example
{
  "content": "mxb.example.com",
  "ttl": 3600,
  "priority": 20,
  "regions": ["global"],
  "integrated_zones": [1, 2, "dnsimple"]
}

Response

Responds with HTTP 200 on success.

{
  "data": {
    "id": 5,
    "zone_id": "example.com",
    "parent_id": null,
    "name": "",
    "content": "mxb.example.com",
    "ttl": 3600,
    "priority": 20,
    "type": "MX",
    "regions": [
      "global"
    ],
    "system_record": false,
    "created_at": "2016-10-05T09:51:35Z",
    "updated_at": "2016-10-05T09:51:35Z"
  }
}

Errors

Responds with HTTP 400 if the record cannot be updated.

Responds with HTTP 401 in case of case of authentication issues.

Delete a zone record

DELETE /:account/zones/:zone/records/:record

Parameters

Name Type Description
:account integer The account id
:zone string The zone name
:record integer The record id

Example

Delete the record with ID 5 for zone example.com, in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X DELETE \
      https://api.dnsimple.com/v2/1010/zones/example.com/records/5

Response

Responds with HTTP 204 on success.

Errors

Responds with HTTP 400 if the record cannot be deleted.

Responds with HTTP 401 in case of case of authentication issues.

Batch change zone records

This endpoint is currently in Public Preview. During the Preview, period changes may occur at any time.

Consider using our official clients to reduce the likelihood of breaking changes. If you are using or planning to use this endpoint we'd like to hear your feedback.

POST /:account/zones/:zone/batch

This endpoint allows you to perform multiple record operations (create, update, and/or delete) for a zone in a single request for efficiency and atomicity. Any combination of create, update, and/or delete operations can be specified, though the total number of operations per request is subject to a maximum limit. Operations are processed in the following order: deletes, followed by updates, then creates.

Zones linked to Integrated DNS Providers do not support batch changes.

The batch change zone records API feature is only available on the Enterprise plan. If the feature is not enabled, you will receive an HTTP 412 response code.

Parameters

Name Type Description
:account integer The account id
:zone string The zone name

Example

Perform a batched change on records for the zone example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -X POST \
      -d '<json>' \
      https://api.dnsimple.com/v2/1010/zones/example.com/batch

Input

All operation types are optional. You can specify any combination of creates, updates, and deletes, as long as you respect the maximum batch size.

Name Type Description
creates array Optional. Array of zone records to create
updates array Optional. Array of zone records to update
deletes array Optional. Array of zone record IDs to delete

Creates

Each item in the creates array represents a record to be created and has the following fields:

Name Type Description
name string Required. The record name, without the domain. The domain will be automatically appended. Use an empty string to create a record for the apex.
type string Required.
content string Required.
ttl integer  
priority integer  
regions array Optional set of regions

Updates

Each item in the updates array represents a record to be updated and has the following fields:

Name Type Description
id integer Required. The ID of the zone record to update
name string The record name, without the domain. The domain will be automatically appended. Use an empty string to create a record for the apex.
content string  
ttl integer  
priority integer  
regions array Optional set of regions

Deletes

Each item in the deletes array requires only an id field:

Name Type Description
id integer Required. The ID of the zone record to delete
Example
{
  "creates": [
    {
      "name": "ab",
      "type": "A",
      "content": "3.2.3.4",
      "ttl": 3600
    },
    {
      "name": "ab",
      "type": "A",
      "content": "4.2.3.4",
      "ttl": 3600
    }
  ],
  "updates": [
    {
      "id": 67622534,
      "content": "3.2.3.40"
    },
    {
      "id": 67622537,
      "content": "5.2.3.40"
    }
  ],
  "deletes": [
    {
      "id": 67622509
    },
    {
      "id": 67622527
    }
  ]
}

Response

Responds with HTTP 200 on success.

{
  "data": {
    "creates": [
      {
        "id": 67623409,
        "zone_id": "example.com",
        "parent_id": null,
        "name": "ab",
        "content": "3.2.3.4",
        "ttl": 3600,
        "priority": null,
        "type": "A",
        "regions": [
          "global"
        ],
        "system_record": false,
        "created_at": "2025-09-05T05:25:00Z",
        "updated_at": "2025-09-05T05:25:00Z"
      },
      {
        "id": 67623410,
        "zone_id": "example.com",
        "parent_id": null,
        "name": "ab",
        "content": "4.2.3.4",
        "ttl": 3600,
        "priority": null,
        "type": "A",
        "regions": [
          "global"
        ],
        "system_record": false,
        "created_at": "2025-09-05T05:25:00Z",
        "updated_at": "2025-09-05T05:25:00Z"
      }
    ],
    "updates": [
      {
        "id": 67622534,
        "zone_id": "example.com",
        "parent_id": null,
        "name": "update1-1757049890",
        "content": "3.2.3.40",
        "ttl": 3600,
        "priority": null,
        "type": "A",
        "regions": [
          "global"
        ],
        "system_record": false,
        "created_at": "2025-09-05T04:40:15Z",
        "updated_at": "2025-09-05T05:25:00Z"
      },
      {
        "id": 67622537,
        "zone_id": "example.com",
        "parent_id": null,
        "name": "update2-1757049890",
        "content": "5.2.3.40",
        "ttl": 3600,
        "priority": null,
        "type": "A",
        "regions": [
          "global"
        ],
        "system_record": false,
        "created_at": "2025-09-05T04:40:22Z",
        "updated_at": "2025-09-05T05:25:00Z"
      }
    ],
    "deletes": [
      {
        "id": 67622509
      },
      {
        "id": 67622527
      }
    ]
  }
}

Errors

Responds with HTTP 400 if validation fails for an operation. The error response includes details about the failed operation:

{
  "message": "Validation failed",
  "errors": {
    "creates": [
      {
        "index": 0,
        "message": "Validation failed",
        "errors": {
          "record_type": [
            "unsupported"
          ]
        }
      }
    ]
  }
}

{
  "message": "Validation failed",
  "errors": {
    "updates": [
      {
        "index": 0,
        "message": "Record not found ID=99999999"
      }
    ]
  }
}

{
  "message": "Validation failed",
  "errors": {
    "deletes": [
      {
        "index": 0,
        "message": "Record not found ID=67622509"
      }
    ]
  }
}

Responds with HTTP 401 in case of authentication issues.

Responds with HTTP 404 if the zone is not found.

Check zone record distribution

Checks if a zone change is fully distributed to all our nameservers across the globe.

GET /:account/zones/:zone/records/:record/distribution

This feature is not available for testing in our Sandbox environment.

Parameters

Name Type Description
:account integer The account id
:zone string The zone name
:record integer The record id

Example

Check the zone record distribution for example.com in the account 1010:

curl  -H 'Authorization: Bearer <token>' \
      -H 'Accept: application/json' \
      https://api.dnsimple.com/v2/1010/zones/example.com/records/5/distribution

Response

Responds with HTTP 200 when the zone record is fully distributed.

{
  "data": {
    "distributed": true
  }
}

Responds with HTTP 200 when the zone record is not distributed.

{
  "data": {
    "distributed": false
  }
}

Errors

Responds with HTTP 401 in case of case of authentication issues.

Responds with HTTP 504 when the server failed to perform the check.

{
  "message": "Could not query zone, connection timed out"
}