Need help? Call Live Support at +31 (0) 38 453 07 59

Attention! You're currently using the OT&E environment.

Used to update a domain name. Only specified fields are updated, to remove an optional field specify it as empty.

For more information about DNS zone operations and the interactions with domains see our Knowledge Base and the DNS operations tab below.

  • POSTMethod
  • /v2/domains/domainName/updateURL
  • application/jsonContent-Type
Name Type Description Restrictions
domainName String The domain name
  • Regular expression: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$
  • Minimum length: 3
  • Maximum length: 255
  • Registry specific restrictions may apply
Name Type Required / Optional Description Restrictions
quote Boolean Optional If true, validate the request and request a quote for the action
Name Type Required / Optional Description Restrictions
registrant String Optional New registrant handle for the domain
  • Regular expression: [a-zA-Z0-9\-_@\.]+
  • Minimum length: 3
  • Maximum length: 40
privacyProtect Boolean Optional Privacy protect setting
authcode String Optional The new auth code for the domain name, if specified as empty string ("") a new random auth code will be generated
  • Maximum length: 64
autoRenew Boolean Optional The auto renew setting for the domain name
autoRenewPeriod Integer Optional Auto renewal period in months. Registry specific values are available in metadata.
ns List <String> Optional List of name servers to use for the domain name, to remove all name servers specify as empty list ([]). If a managed zone exists and the name servers are changed the managed zone is deleted after 7 days. If you want to change the vanity name servers of a zone, make sure the "zone" field is specified.
  • Regular expression: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$
  • Maximum number of items: 10
  • Minimum length: 4
  • Maximum length: 255
status List <Enum> Optional New domain statuses, you can only add and remove CLIENT statuses, IRTPC_TRANSFER_PROHIBITED can only be removed, other statuses must remain unchanged

Possible values:

  • OK: Ok
  • INACTIVE: Inactive
  • PENDING_TRANSFER: Pending transfer
  • PENDING_RENEW: Pending renew
  • PENDING_UPDATE: Pending update
  • DELETE_REQUESTED: Delete requested
  • PENDING_DELETE: Pending delete
  • ADD_PERIOD: Add period
  • RENEW_PERIOD: Renew period
  • AUTO_RENEW_PERIOD: Auto renew period
  • TRANSFER_PERIOD: Transfer period
  • REDEMPTION_PERIOD: Redemption period
  • PENDING_RESTORE: Pending restore
  • CLIENT_HOLD: Client hold
  • CLIENT_DELETE_PROHIBITED: Client delete prohibited
  • CLIENT_UPDATE_PROHIBITED: Client update prohibited
  • CLIENT_RENEW_PROHIBITED: Client renew prohibited
  • CLIENT_TRANSFER_PROHIBITED: Client transfer prohibited
  • REGISTRAR_HOLD: Registrar hold
  • REGISTRAR_DELETE_PROHIBITED: Registrar delete prohibited
  • REGISTRAR_UPDATE_PROHIBITED: Registrar update prohibited
  • REGISTRAR_RENEW_PROHIBITED: Registrar renew prohibited
  • REGISTRAR_TRANSFER_PROHIBITED: Registrar transfer prohibited
  • SERVER_HOLD: Server hold
  • SERVER_DELETE_PROHIBITED: Server delete prohibited
  • SERVER_UPDATE_PROHIBITED: Server update prohibited
  • SERVER_RENEW_PROHIBITED: Server renew prohibited
  • SERVER_TRANSFER_PROHIBITED: Server transfer prohibited
  • PENDING_VALIDATION: Domain pending registrant validation
  • PRIVACY_PROTECT_PROHIBITED: Privacy protect prohibited
  • EXPIRED: Domain has expired
  • IRTPC_TRANSFER_PROHIBITED: Transfer prohibited due to IRTP-C
designatedAgent Enum Optional Indicates for whom you are acting as a designated agent. If a registry does not allow you to be designated agent or interaction with the registrant is still required this parameter is silently ignored. To use this field with any other value then "NONE" the requesting user must have the "DESIGNATED_AGENT" permission.

Possible values:

  • NONE
  • OLD
  • NEW
  • BOTH
zone zone Optional DNS template to use for the domain name, to remove an existing zone without creating a new one omit this field and specify the "ns" field as an empty list ([])
  • In case a existing zone is used the values the values must match the existing zone or be left empty
contacts List < contacts > Optional Domain contacts and their role
keyData List < keyData > Optional DNSSEC Key data for domain, to remove all DS data records specify as empty list ([])
dsData List < dsData > Optional DNSSEC DS data for domain, the system does not accept new DS data records, this field can only be used to remove DS data records. If a matching key data record is added the corresponding DS data record is automatically removed. To remove all DS data records specify as empty list ([])
billables List < billables > Optional Acknowledgment of billables for this request
Name Type Required / Optional Description Restrictions
service Enum Optional DNS service to provision, defaults to BASIC for new zone, otherwise the service of the existing managed zone

Possible values:

  • BASIC: Basic, free DNS
  • PREMIUM: Premium DNS
template String Optional The template to use, removes any existing records/master
  • Regular expression: [a-zA-Z0-9\-_@\.]+
  • Minimum length: 3
  • Maximum length: 40
link Boolean Optional Unless false, the zone is linked to the template
master String Optional The IP address of the (hidden) master, removes any existing records/template
dnssec Boolean Optional DNSSEC signing service for zone
managed Boolean Optional Used to convert a managed zone to unmanaged by specifying als 'false'
Name Type Required / Optional Description Restrictions
role Enum Required The role for the contact

Possible values:

  • ADMIN
  • BILLING
  • TECH
handle String Required The contact handle
  • Regular expression: [a-zA-Z0-9\-_@\.]+
  • Minimum length: 3
  • Maximum length: 40
Name Type Required / Optional Description Restrictions
protocol Integer Required The DNSSEC protocol

Possible values:

  • 3
flags Integer Required The DNSSEC flags

Possible values:

  • 256: 256 (ZSK)
  • 257: 257 (KSK)
algorithm Integer Required The DNSSEC algorithm

Possible values:

  • 3: 3 (DSA/SHA1)
  • 5: 5 (RSA/SHA-1)
  • 6: 6 (DSA-NSEC3-SHA1)
  • 7: 7 (RSASHA1-NSEC3-SHA1)
  • 8: 8 (RSA/SHA-256)
  • 10: 10 (RSA/SHA-512)
  • 12: 12 (GOST R 34.10-2001)
  • 13: 13 (ECDSA Curve P-256 with SHA-256)
  • 14: 14 (ECDSA Curve P-384 with SHA-384)
  • 15: 15 (Ed25519)
  • 16: 16 (Ed448)
publicKey String Required The base64 encoded public key
Name Type Required / Optional Description Restrictions
keyTag Integer Required The DNSSEC keyTag
  • Maximum value: 65536
  • Minimum value: 0
algorithm Integer Required The DNSSEC algorithm

Possible values:

  • 3: 3 (DSA/SHA1)
  • 5: 5 (RSA/SHA-1)
  • 6: 6 (DSA-NSEC3-SHA1)
  • 7: 7 (RSASHA1-NSEC3-SHA1)
  • 8: 8 (RSA/SHA-256)
  • 10: 10 (RSA/SHA-512)
  • 12: 12 (GOST R 34.10-2001)
  • 13: 13 (ECDSA Curve P-256 with SHA-256)
  • 14: 14 (ECDSA Curve P-384 with SHA-384)
  • 15: 15 (Ed25519)
  • 16: 16 (Ed448)
digestType Integer Required The DNSSEC digest type

Possible values:

  • 1: 1 (SHA-1)
  • 2: 2 (SHA-256)
  • 3: 3 (GOST R 34.11-94)
  • 4: 4 (SHA-384)
digest String Required The digest of the public key
Name Type Required / Optional Description Restrictions
product String Required The product
action Enum Required The action

Possible values:

  • CREATE
  • REQUEST
  • TRANSFER
  • RENEW
  • RESTORE
  • TRANSFER_RESTORE
  • UPDATE
  • REGISTRANT_CHANGE
  • LOCAL_CONTACT
  • NEGATIVE_MARKUP
  • PRIVACY_PROTECT
  • EXTRA_WILDCARD
  • EXTRA_DOMAIN
  • REGISTRY_LOCK
quantity Integer Optional The maximum quantity, default 1

Successful request

  • 200 OKHTTP Status
  • application/jsonContent-Type
  • 202 AcceptedHTTP Status

Failed requests

Besides the generic errors these specific error responses can be expected.

Type Status Description
BillableAcknowledgmentNeededException 400 Bad Request
The domain name
If true, validate the request and request a quote for the action
New registrant handle for the domain
Privacy protect setting

Specify as empty string: The new auth code for the domain name, if specified as empty string ("") a new random auth code will be generated
The auto renew setting for the domain name
Auto renewal period in months. Registry specific values are available in metadata.

Specify as empty list: List of name servers to use for the domain name, to remove all name servers specify as empty list ([]). If a managed zone exists and the name servers are changed the managed zone is deleted after 7 days. If you want to change the vanity name servers of a zone, make sure the "zone" field is specified.
New domain statuses, you can only add and remove CLIENT statuses, IRTPC_TRANSFER_PROHIBITED can only be removed, other statuses must remain unchanged
Indicates for whom you are acting as a designated agent. If a registry does not allow you to be designated agent or interaction with the registrant is still required this parameter is silently ignored. To use this field with any other value then "NONE" the requesting user must have the "DESIGNATED_AGENT" permission.
DNS service to provision, defaults to BASIC for new zone, otherwise the service of the existing managed zone
The template to use, removes any existing records/master
The IP address of the (hidden) master, removes any existing records/template
DNSSEC signing service for zone
Used to convert a managed zone to unmanaged by specifying als 'false'
The role for the contact
The contact handle
The role for the contact
The contact handle
The role for the contact
The contact handle
DNSSEC Key data for domain, to remove all DS data records specify as empty list ([])
The DNSSEC protocol
The DNSSEC flags
The DNSSEC algorithm
The base64 encoded public key
DNSSEC DS data for domain, the system does not accept new DS data records, this field can only be used to remove DS data records. If a matching key data record is added the corresponding DS data record is automatically removed. To remove all DS data records specify as empty list ([])
The DNSSEC keyTag
The DNSSEC algorithm
The DNSSEC digest type
The digest of the public key
The product
The action
The maximum quantity, default 1

POST /v2/domains/domainName/update
Content-Type: application/json

{}

Many different scenarios for changes to DNS settings exist, below are general rules to follow and examples for common scenarios.

General rules for managed zones

  • If a managed zone exists and the name servers of a domain are changed the zone is marked for removal in 7 days. If you wish to change the (vanity) name servers of a existing zone make sure to specify the 'zone' field, its content may be empty ({}) or have fields specified.
  • If 'zone' is specified but 'zone.service' is not, it defaults to the service of the existing managed zone, or if not present falls back to 'BASIC'.
  • If an existing master zone is converted to a slave zone, the master of a slave zone is changed, or the NS records on the master are changed; the name servers of the domain are not automatically changed, instead the name servers need to be specified in the update call when a change is needed.
  • If a zone already exists, only fields changed on the zone need to be specified.

Zone provisioning

The way the records are provisioned can be changed both via update domain and update zone, some examples for update domain

{
      "zone": {
        "link": false
      }
}
{
      "zone": {
        "template": "example"
      }
}
{
      "zone": {
        "master": "1.2.3.4"
      }
}
{
      "zone": {
        "master": ""
      }
}

Change service

It is possible to change DNS service, migrating the existing records to the new service. If the zone currently has a master only the records and a optional link with a template are migrated, the master synchronisation is not. The zone at the old service is marked for deletion in 7 days.

A zone of the target service must not yet exist, otherwise the existing zone is adopted.

{
      "zone": {
        "service": "BASIC"
      }
}

Vanity name servers

To avoid deletion of a zone, always specify the zone field when changing vanity name servers.

For details on how to setup correct resolution of vanity name server see our Knowledge Base

{
      "ns": ["ns1.yourname.com", "ns2.yourname.com"],
      "zone": {
        "service": "PREMIUM",
        "template: "example"
      }
}
{
      "ns": ["ns1.yourname.com", "ns2.yourname.com"],
      "zone": {}
}

Zone deletion

{
      "ns": ["ns1.other.com", "ns2.other.com"]
}
{
      "ns": []
}

Zone adoption

Adoption of zones cannot be combined with changes to the zone, the service must be specified to adopt other a zone other than BASIC. Other zone field must be omitted or equal to the current zone.

If the current zone is pending deletion it can be reinstated and adopted by, if however a template or master is specified a new zone will be created instead and the pending deletion zone is removed immediately.

{
      "zone": {}
}

Decouple zone

After decoupling, both the zone and domain remain unchanged, however any future changes to the zone or domain that are interdependent are not synchronised automatically anymore. e.g. dnssec changes, vanity name server changes, key rollover, zone cleanup after domain deletion.

This is not supported on BASIC zones since those are only ever active in DNS when in a managed state.

This can be useful if you want to transfer the domain but keep the zone active.

{
      "zone": {
        "managed": false
      }
}