Batch Change Zone Records API

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.