API release 1.1 documentation

Contents

• Overview
• Data types
• Contact details
• Name server details
• Resource record details
• DS record details
• Implied credentials
• Examples
• Registration terms
• General exceptions
• Nomenclature
• price
• check_availability
• register_domain_name
• import_nz_domain_name
• import_other_domain_name
• domain_names
• domain_name
• update_domain_name
• update_contacts
• update_name_servers
• dns_zones
• dns_zone
• configure_zone
• create_dns_record
• update_dns_record
• delete_dns_record
• update_ds_records
• set_http_redirection
• renew_domain_name
• domain_name_is_locked
• lock_domain_name
• unlock_domain_name
• reset_domain_name_secret
• account_balance
• transactions

Overview

• This API is based on JSON-RPC
• The API endpoint is https://metaname.net/api/1.1
• Your JSON-RPC library will handle the details but roughly:
• Your software makes an HTTPS POST request to the API endpoint
• The body of the request is a data structure encoded in JSON.
• The data structure includes the name of remote method that should be invoked along with data structures for all arguments to the method
• Arguments may not be objects but may be arbitrarily complex compositions of scalars, lists and maps. See Data types for all supported data types

Data types

The API supports all JSON data types, which are:

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:

• "A"
• "AAAA"
• "CNAME"
• "MX"
• "TXT"

..but may also be one of:

• "DNSKEY"
• "LOC"
• "PTR"
• "RRSIG"
• "SSHFP"
• "SRV"

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:

• .nz names accept between 1 and 120 months at a time. The maximum term that may be pre-paid at any time is 120 months, so registering for 120 months and then immediately renewing for 120 months is not permitted
• Most non-NZ names accept terms between 1 and 10 years, specified in months. "12" and "36" are permitted, "1" or "18" are not
• .mobi and .au accept terms in units of 24 months. "24" and "72" are permitted, "1", "12" or "36" are not

General exceptions

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

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

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

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.

eligibility_type:     "Club"
eligibility_id_type:  "ABN"
eligibility_id:       "99 000 000 000"
registrant_id_type:   "ACN"
registrant_id:        "000 000 000"

--- 
net: &id001 
  Sole Trader: ABN
  Company: ACN
  Trademark Owner: TM
  Pending Trademark Owner: TM
  Partnership: ABN
"": 
  Citizen/Resident: OTHER
  Sole Trader: ABN
  Company: ACN
  Trademark Owner: TM
  Pending Trademark Owner: TM
  Partnership: ABN
com: *id001
org: 
  Non-profit Organization: 
  - ABN
  - ACT BN
  - ACN
  - NSW BN
  - NT BN
  - QLD BN
  - SA BN
  - TAS BN
  - VIC BN
  - WA BN
  - OTHER
  Charity: ABN
  Club: ABN
  Incorporated Association: 
  - ACT BN
  - NSW BN
  - NT BN
  - QLD BN
  - SA BN
  - TAS BN
  - VIC BN
  - WA BN
  Trade Union: OTHER

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

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

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

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

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

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

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

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:

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

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

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

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

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

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:

• key_tag: Number
• algorithm: Number such as 8 for RSA/SHA-256
• digest_type: Number
• digest: String in hexadecimal, no spaces

Exceptions

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

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

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

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

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

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

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:

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