API release 1.1 documentation

Contents

Overview

Data types

The API supports all JSON data types, which are:

Type Notes
Boolean true or false
Number double precision floating point
String with Unicode support
Array a list of objects of any type
Object really a map of key, value pairs. The keys must be strings but the values may be of any type
null unknown or not applicable

Contact details

Some methods accept or provide contact details. These are maps like this:

name:             "Joe Bloggs"
email_address:    "joe@example.co.nz"
organisation_name: null  # Only for non-.nz names
postal_address:
   line1:        "15 Example Ave"
   line2:         null
   city:         "Exampleton"
   region:        null
   postal_code:  "1234"
   country_code: "NZ"
phone_number:
   country_code: "64"
   area_code:    "3"
   local_number: "123 456"
fax_number: null  # Optional

Most keys such as name and email_address are essential, so the value must be present and valid. fax_number is optional. When fax_number maps to a value of null then the fax number will be removed from the registry.

organisation_name is optional. It is ignored for .nz names but required for non-NZ names. A value of "individual" can be used for personal registrations where no organisation is involved.

All keys must be present even if they map to a value of null.

Name server details

Some methods accept or provide details of name servers. These are maps like this:

name:        "ns1.example.co.nz"
ip4_address: "203.0.113.1"
ip6_address: "2001:db8::1"

name is always required and should be a valid fully-qualified domain name such as in the example above.

ip4_address should be provided for name servers that in-zone but should not be provided for name servers that are out-of-zone. As an example, an IP address should be supplied for ns1.metaname.net when configured for the metaname.net zone but should be absent when configured on example.co.nz.

ip6_address should be provided or not based on the same in-zone criteria as for ip4_address. Additionally, ip6_address may not be present without an accompanying ip4_address.

All keys must be present even if they map to a value of null.

Resource record details

Some methods accept or provide details of DNS resource records (RRs). These are maps like this:

reference: "our-ref"
name:      "www"
type:      "A"
aux:        null  # ..or a number such as 10 for MX and SRV records
ttl:        86400
data:      "203.0.113.1"

reference is provided by the dns zone method but should not be present in resource record objects when they are passed as parameters to the API. References can of course be passed on their own as parameters in order to identify a particular resource record.

name, and data are Strings and correspond to the owner and data fields as specified in the relevant RFCs.

type is commonly one of:

..but may also be one of:

aux should be null except for MX or SRV records when it should be a Number. This corresponds to the priority field in the relevant RFCs.

ttl is specified as a Number of seconds.

DS record details

Some methods accept or provide details of Delegation Signer (DS) records. These are maps like this:

key_tag:      1
algorithm:    8
digest_type:  1
digest:       7893883873a705aec69e2942901f20d7b1e28dec

key_tag must be an integer in the range 0..65535.

algorithm must be one of 5, 7, 8, 10, 13, 14, 15 or 16.

digest_type must be either 1, 2 or 4.

digest must be a hex digest of the correct length for digest_type (40 digits for a SHA-1 digest, 64 for SHA-256, etc.).

Implied credentials

The first two parameters to every method should be:

  1. account_reference: The four-digit reference of your Metaname account
  2. api_key: Your API key. This is separate from the password to your account so that it may be changed independently

These parameters are omitted from method descriptions for brevity, so the following:

account_balance()
dns_zone( domain_name)

..really mean:

account_balance( account_reference, api_key)
dns_zone( account_reference, api_key, domain_name)

Examples

Request

{"jsonrpc":"2.0", "id":"2e", "method":"price",
 "params":["****","********************************","example.co.nz",1,false]}

Successful response

{"jsonrpc":"2.0", "id":"2e", "result":"2.08"}

Exception

{"jsonrpc":"2.0", "id":"3z", "error":{"message":"Invalid domain name", "code":-4}}

Registration terms

This information applies both to the initial term of a newly registered name and also when the pre-paid term is extended (by renewing the name).

The permitted duration of terms varies across registries. A rough guide is:

General exceptions

In addition to the exceptions described for each method, the following exceptions can be raised by any JSON-RPC request:

Code Message
-1 Authentication failed
-32700 Parse error
-32600 Invalid Request
-32601 Method not found
-32602 Invalid params
-32603 Internal error

Control flow based on the contents of the message and data fields should be avoided where convenient to insulate against possible future changes to these values.

Nomenclature

Any references to "UDAI" or "UDAIs" should be read as "auth code" or "auth codes". UDAI is an old term for what is now known auth code for .nz names.

price

Synopsis

price( domain_name, term, renewal): String

Provides the GST-inclusive price either to register or to renew a domain name for the specified term.

Parameters

term is specified in months. Valid terms vary by registry.

renewal should be true to request the price of a renewal or false to request the price for a registration.

Exceptions

Code Message Meaning
-4 Invalid domain name The domain name was either not valid or not a supported TLD
-7 Invalid term

check_availability

Synopsis

check_availability( domain_name, source_ip): String

Determines the availability of a domain name.

Parameters

source_ip should be the IP address of the system making the request. If the request is being made on behalf of a customer then this parameter should be the IP address of the web client accessing your system. Both IPv4 and IPv6 addresses are supported. For requests originating within your system (e.g. batch processing) this field may be null.

Return value

The return value will be available if the domain name is available for registration. All other return values indicate that the domain name is not available for registration. Currently, the only other possible return value is taken although more specific values may be defined in the future.

Exceptions

Code Message
-4 Invalid domain name

register_domain_name

NOTE: Please do not use this API endpoint to "backorder" domain names because requests to register domain names newly Available will be declined by the .nz registry from 2022 November 1st onward.

Synopsis

register_domain_name( domain_name, term, contacts, name_servers): String

Registers a domain name.

Parameters

term should be the Number of months to register the domain name for initially.

contacts should be a map that may have registrant, admin and technical keys. If default contact details have been set up for your account then keys may be left out in which case the default contact details will be used. Any keys that are included must map to contact details.

.au names

name_servers should either be null in which case Metaname hosted DNS will serve the new domain name, or a list of details of name servers.

Return value

For .nz names, the auth code is provided. For non-NZ names the return value is null.

Exceptions

Code Description
-4 Invalid domain name
-6 No account default contact
-7 Invalid term
-8 Invalid contact
-9 Invalid name server
-11 Transaction declined
-99 Domain name is already registered

import_nz_domain_name

Synopsis

import_nz_domain_name( domain_name, udai): String

Transfers a .nz name to your Metaname account.

The contact details and name server authorities remain the same when a .nz name is transferred between registrars.

Return value

The new auth code is provided upon successful transfer of the name.

Exceptions

Code Description
-4 Invalid domain name
-15 Invalid UDAI
-18 Upstream error

import_other_domain_name

Synopsis

import_other_domain_name( domain_name, contacts): null

Initiates the transfer of a non-NZ name to your Metaname account.

The admin contact of record will be e-mailed a URL that includes the transfer key (which is not the same as an authentication code). The admin contact should obtain the authentication code from the existing registrar and input it on the page to which the URL from the e-mail points. The transfer will then be processed and will typically take 5 to 10 days to complete. Metaname will send an e-mail when the transfer completes and the status of the name will change from "Transferring" to "Active".

Non-NZ names must be renewed for the minimum term (typically 12 months) at the time of transfer between registrars. Your Metaname account will be billed for this renewal when the transfer completes.

Parameters

contacts should specify the contact details that will be applied to the name after the transfer and should be a map that may have registrant, admin and technical keys. If default contact details have been set up for your account then keys may be omitted in which case the default contact details will be used. Any keys that are included must map to contact details.

Name server authorities are preserved throughout a transfer.

Exceptions

Code Description
-4 Invalid domain name
-6 No account default contact
-8 Invalid contact
-18 Upstream error

domain_names

Synopsis

domain_names(): Array

Provides a list of all of the domain names in the Metaname account.

Return value

Each item in the list is a map with the following keys:

name:            "example.co.nz"
status:          "Active"  # Other possibilities are "Transferring", "PendingRelease", "Locked" and "Provisional"
when_registered: "2010-01-01T12:34:56"  # dates and times use ISO 8601 format and in local (NZ) time
when_paid_up_to: "2020-01-01T12:34:56"
when_canceled:    null  # i.e. the domain name has not been canceled
when_locked:      null  # i.e. the domain name has not been locked
belongs_to_set:  "My domain names"
uses_dns_hosting: false
redirected_to:    null  # indicates that HTTP redirection is disabled
contacts:
   registrant:
      ..see #Contact_details near the beginning of this document
   admin:
      ..see #Contact_details near the beginning of this document
   technical:
      ..see #Contact_details near the beginning of this document
name_servers:
   - ..see #Name_server_details near the beginning of this document
   - ...
ds_records:
   - ..see #DS_record_details near the beginning of this document
   - ...
auto_renew_term: 12   # or null if the domain name is set to expire

Each of the keys in the contacts map must map to contact details and each element of the name_servers list must map to name server details.

domain_name

Synopsis

domain_name( domain_name): Object

Provides details of the specified domain name.

Return value

An Object with these keys:

name:            "example.co.nz"
status:          "Active"  # Other possibilities are "Transferring", "PendingRelease", "Locked" and "Provisional"
when_registered: "2015-09-14T11:24:13+12:00"  # Dates and times use ISO 8601 format with time zones
when_paid_up_to: "2016-09-14T11:24:13+12:00"
contacts:
   registrant:
      ..see #Contact_details near the beginning of this document
   admin:
      ..see #Contact_details near the beginning of this document
   technical:
      ..see #Contact_details near the beginning of this document
name_servers:
   - ..see #Name_server_details near the beginning of this document
   - ...
ds_records:
   - ..see #DS_record_details near the beginning of this document
   - ...
auto_renew_term: 12

Exceptions

Code Message
-4 Invalid domain name
-5 Domain name not found

update_domain_name

Synopsis

update_domain_name( domain: Object): null

Updates the details of a domain name, currently only whether it should be renewed automatically at term and how long for, and the "set" (group) that it belongs to.

Parameters

domain is an Object with these keys:

name:            "example.co.nz"
auto_renew_term:  12
belongs_to_set:  "badger"

name indicates the domain name that should be updated.

auto_renew_term is the :Number of months that the domain should be renewed for once it reaches term. A value of 0 indicates that the domain name should not be renewed.

belongs_to_set:String is the name of the set that this domain name should belong to. If no such set exists then a set with this name will be created.

Exceptions

Code Description
-4 Invalid domain name
-5 Domain name not found
-7 Invalid term
-20 Invalid data
-18 Upstream error

update_contacts

Synopsis

update_contacts( domain_name, contacts): null

Updates the contact details for the specified domain name.

Parameters

contacts should be a map that may have registrant, admin and technical keys. If default contact details have been set up for your account then keys may be omitted in which case the default contact details will be used. Any keys that are included must map to contact details.

Exceptions

Code Message
-4 Invalid domain name
-5 Domain name not found
-6 No account default contact
-8 Invalid contact
-18 Upstream error

update_name_servers

Synopsis

update_name_servers( domain_name, name_servers): null

Changes the servers that should serve DNS requests for the specified domain name.

Parameters

name_servers should be null if the domain name should be served by Metaname hosted DNS. Otherwise, it should be a list of details of name servers.

A domain name may not be configured with custom name servers while HTTP redirection is active.

Exceptions

Code Message
-4 Invalid domain name
-5 Domain name not found
-9 Invalid name server
-13 HTTP redirection is enabled
-18 Upstream error

dns_zones

Synopsis

dns_zones(): Array

Provides a list of the DNS zones in the Metaname account.

Return value

A list of DnsZone objects. Each object has keys:

Field Purpose
name:String The name of the zone that may be supplied to the dns_zone method

The list is ordered by zone name.

dns_zone

Synopsis

dns_zone( domain_name): Array

Provides a list of RRs if the specified domain name uses Metaname hosted DNS.

Return value

A list of resource record details.

Exceptions

Code Message
-4 Invalid domain name
-5 Domain name not found
-12 DNS hosting not enabled

configure_zone

Synopsis

configure_zone( zone_name, resource_records, options): null

Creates or updates the named zone and publishes it to the hosted name servers.

Parameters

zone_name: String. The name of the zone to create or update. If this is the name of a domain name managed at Metaname and the domain name is configured to use Metaname name servers then this method updates the resource records for that domain name.

resource_records: Array[ Object]. A list of resource records. Each item on the list should be a map of resource record details.

options: Object.: A map of options. May be null or an empty map but in future may allow for management of signed and/or slave zones.

Exceptions

Code Description
-21 Invalid zone name
-20 Invalid data
-18 Upstream error

Error -20 is returned when there is a zone conflict such as if two separate accounts attempt to publish zones with the same name.

create_dns_record

Synopsis

create_dns_record( domain_name, record): String

Add a new RR to the zone for a domain name that uses Metaname hosted DNS.

Parameters

record should be a map of resource record details.

Return value

A reference for the new RR that may be used to update and/or remove the RR.

Exceptions

Code Message
-4 Invalid domain name
-5 Domain name not found
-12 DNS hosting not enabled
-16 Invalid DNS record

update_dns_record

Synopsis

update_dns_record( domain_name, reference, record): null

Updates the details of a RR in the zone of a domain name that uses Metaname hosted DNS.

Parameters

reference is the reference of an RR. RR references are provided in response to the dns zone or create dns record methods.

record should be a map of resource record details.

Where keys are absent then the related field retains its existing value.

Exceptions

Code Description
-4 Invalid domain name
-5 Domain name not found
-12 DNS hosting not enabled
-16 Invalid DNS record
-17 DNS record not found

delete_dns_record

Synopsis

delete_dns_record( domain_name, reference): null

Removes the specified RR from the zone of a domain name that uses Metaname hosted DNS.

Parameters

reference is the reference of an RR. RR references are provided in response to the dns zone or create dns record methods.

Exceptions

Code Description
-4 Invalid domain name
-5 Domain name not found
-12 DNS hosting not enabled
-17 DNS record not found

update_ds_records

Synopsis

update_ds_records( domain_name, ds_records): null

Changes the list of DS records published for the specified domain_name in its parent zone. Only .nz names are supported at the moment.

Parameters

ds_records should be a list of DS records, which are objects with the following keys:

Exceptions

Code Description
-4 Invalid domain name
-20 Invalid data
-5 Domain name not found
-18 Upstream error

set_http_redirection

Synopsis

set_http_redirection( domain_name, redirection_uri): null

Configures HTTP redirection for the specified domain name.

Parameters

redirection_uri must be a valid HTTP URI or null if HTTP redirection should be disabled for the specified domain name, which must be configured for Metaname hosted DNS.

Exceptions

Code Description
-4 Invalid domain name
-5 Domain name not found
-10 Invalid URI
-12 DNS hosting not enabled

renew_domain_name

Synopsis

renew_domain_name( domain_name, term): null

Adds the specified term to the period that is pre-paid for a domain name. This is called an "advance renewal".

Parameters

term should be the Number of months by which the pre-paid period should be extended. See registration terms for a description of the acceptable values for this parameter.

Exceptions

Code Description
-4 Invalid domain name
-5 Domain name not found
-11 Transaction declined

domain_name_is_locked

Synopsis

domain_name_is_locked( domain_name): Boolean

Determines if the specified domain_name is locked at the registry or not. Note that .nz names cannot be locked and that exceptions are raised by this method for names that do not support locking.

Return value

true if the domain name is locked, or false otherwise.

Exceptions

Code Description
-4 Invalid domain name
-5 Domain name not found
-18 Upstream error
-19 Locking is unsupported for this domain name

lock_domain_name

Synopsis

lock_domain_name( domain_name): null

Locks the specified domain_name at the registry. Note that .nz names cannot be locked and that exceptions are raised by this method for names that do not support locking.

Exceptions

Code Description
-4 Invalid domain name
-5 Domain name not found
-18 Upstream error
-19 Locking is unsupported for this domain name

unlock_domain_name

Synopsis

unlock_domain_name( domain_name): null

Unlocks the specified domain_name at the registry. Names must be unlocked before they can be transferred to another registrar. Although names must be unlocked in other situations such as when updating contact details, Metaname manages this unlocking and locking automatically (if the names are locked to begin with) for registries and situations where it is required.

Exceptions

Code Description
-4 Invalid domain name
-5 Domain name not found
-18 Upstream error
-19 Locking is unsupported for this domain name

reset_domain_name_secret

Synopsis

reset_domain_name_secret( domain_name): String

Generates a new authorization code ("auth code") for the specified domain name.

Return value

The new auth code for .nz names or null otherwise in which case the authorisation code is sent to the e-mail address listed for the admin contact.

Exceptions

Code Description
-4 Invalid domain name
-5 Domain name not found
-18 Upstream error

account_balance

Synopsis

account_balance(): String

Provides the current balance of your Metaname account.

Return type

The return type is not a Number but a String that contains a representation of a real number.

transactions

Synopsis

transactions( criteria): Array

Provides a list of transactions on the account that meet the specified criteria.

Parameters

criteria should have this structure:

during_period:
  beginning:  2019-12-01T13:01:59+1300
  end:        2020-01-01T00:00:00+1300

beginning and end are strings in ISO8601 format.

beginning is the time at or after which transactions must have been made in order to be included. Use "2009-01-01T00:00:00+1300" to include the earliest transactions.

end is the time before which transactions must have been made in order to be included. Use times in the future to include the latest transactions.

All parameters and keys are required, none are optional.

Return value

A list of Transaction records. Each record has keys:

Field Purpose
when_happened A timestamp in ISO8601 format indicating the time at which the transaction occurred
amount The value of the transaction to 2 decimal places as a String
description A human-readable description of the purpose of the transaction

No more than 256 transactions will be provided in response to a single invocation. If more than 256 transactions fall within the specified period then Too much data is indicated and multiple shorter periods should be used to retrieve all transactions within the period.

The list of transactions is ordered by the time when they occurred.

Exceptions

Code Description
-66 Too much data