Domains through the API: checking a name, registering, renewing and transferring with credit

The short answer: through the API you list your domains, check whether a name is free and what it costs, register, renew and transfer paying from your account credit, and change nameservers, transfer lock and auto-renewal. Purchases need domains:write, billing:purchase and the Idempotency-Key header.

Listing and checking

Operation	What it does	Permission
GET /v1/domains	The account's domains, next to expire first, in pages. Filter ?status=active.	domains:read
GET /v1/domains/{domain}	One domain, by name or id.	domains:read
GET /v1/domains/availability	Whether a name is free and the one-year price (registration, renewal and transfer).	domains:read

curl "https://api.mozout.com/v1/domains/availability?domain=yourcompany.com" -H "Authorization: Bearer $RLX_API_KEY"

If the check says unknown, it was not possible to confirm right now whether the name is free, and registration through the API will not go ahead. Try again later.

Registering, renewing and transferring

1	Confirm the name and the price with GET /v1/domains/availability.

2	Make the request with POST /v1/domains/register (or /v1/domains/{domain}/renew, or /v1/domains/transfer with the transfer code), always with an Idempotency-Key.

3	Payment comes from your account credit, within the key's spending limit. If credit is short, the price has changed or the account profile is incomplete, nothing is charged.

4	The answer is a 202 with an action_id: follow it as explained in long-running operations.

curl https://api.mozout.com/v1/domains/register -X POST \
-H "Authorization: Bearer $RLX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1d2c3a-8b4e-4f7a-9c21-1d2e3f4a5b6c" \
-d '{"domain": "yourcompany.com", "years": 1}'

A domain cannot be registered for more than 10 years in total. Some extensions, including .mz, are handled manually and take longer. Prices are on the domain pricing page.

What is only done in My MozOut

These cases answer 422 with a portal_url that takes you to the right place in My MozOut:

Case	Why
.mz and .ao names of up to 3 characters	They have their own price.
.ac.mz, .gov.mz and .mil.mz	They require documents.
Extensions that need extra holder details	The details are filled in on My MozOut.
Transfers of .mz and .ao	They are handled in My MozOut.

Nameservers, lock, renewal and contacts

Operation	What it does
GET and PUT /v1/domains/{domain}/nameservers	Read and change the nameservers. Give from 2 to 5.
GET and PUT /v1/domains/{domain}/lock	The transfer lock.
PUT /v1/domains/{domain}/auto-renew	Auto-renewal.
GET /v1/domains/{domain}/contacts	The contacts in the domain record.
POST /v1/domains/{domain}/transfer-code	Requests the transfer code. Needs domains:transfer_code and the name in confirm. The code never appears in the answer: it goes to the account or holder e-mail.

The domain of the account e-mail is protected. If the e-mail you sign in with, or that of one of your users, is on this domain, changing the nameservers answers 409 account_email_domain, in Sandbox too: whoever controls that mail receives password resets and sign-in codes. Make that change in My MozOut.

Nameservers and lock may come from a copy up to 60 seconds old, which does not count towards the limit of 30 reads per minute; contacts are always read live. What you change through the API shows straight away. Changing contacts, the holder, privacy and forwarding is not in the API yet.

Want to register domains from your own system? See the API page and test first with a Sandbox key, which never charges.

See the API page

Categories

Categories