Skip to content

Domain registration

Registrar operations — registering, transferring, and managing TLD registrations and their contacts. This is distinct from Domains, which manages the hostnames attached to WordPress sites.

Feature-flagged

These endpoints are gated by the domain-registration feature flag. When it is off, every endpoint here returns 503 {"errors":[...],"code":"feature_disabled"}.

Account Scope Required (X-Auth-Account) — a missing header returns 400. OAuth scopes: reads domains:read, writes domains:write. Mutations require the can_edit role. Mutations may complete synchronously (200) or open an async registrar process (202 with pending_process). TLDs with no configured registrar return 503 registrar_unavailable; upstream registrar failures return 502.

409 registration_busy does not guard every mutation

While a registration has a registrar process in flight, these actions are rejected with 409 registration_busy: update, nameservers, lock, privacy, dnssec, holder, contacts, push_transfer and registrant_change. force_sync, transfer_out, resend_contact_verification, renew_now and the process resend / cancel endpoints still run.

422 domain_import_held: held registrations are read-only

While a registration is on hold, every change to it, and to a contact it uses, answers 422 domain_import_held until the hold is lifted. Reads still work, except fetching the EPP code.

Registering / transferring a domain is an order

The endpoints here check availability (check / suggestions) and manage existing registrations. To actually register or transfer a domain, place a paid order via POST /api/orders/domain (see the full param surface in Orders). To change a registration's registrant as a paid order, use POST /api/domain_registrations/:id/registrant_change (the billable counterpart to PATCH .../holder).


Domain Contacts

Reusable owner/admin/tech/billing contacts that back domain registrations. A contact is pinned to a single TLD on create because each registry validates a different set of fields. :id is the numeric contact ID.

Domain Contact shape
  • id: Integer
  • handle: String
  • first_name: String
  • last_name: String
  • organization: String
  • street_address: String
  • post_code: String
  • city: String
  • state: String
  • country: String | ISO-2
  • email: String
  • phone: String | E.164, +CC.NUMBER
  • extra_properties: Object | TLD-specific registry fields
  • validations: Array
  • split_from_id: Integer | null
  • created_at: DateTime
  • updated_at: DateTime

List Domain Contacts

GET /api/domain_contacts

Params (optional)
  • q: String | substring match against handle, organization, full name, or registration name

Returns { "domain_contacts": [ ... ] }.

View a Domain Contact

GET /api/domain_contacts/:id

Create a Domain Contact

POST /api/domain_contacts

Creates the contact at the registrar AND locally. Returns 201. You must pass tld_id or tld_name so the right registry rules apply. An unknown TLD returns 404 tld_not_found.

Params
  • tld_id: Integer | one of tld_id / tld_name required
  • tld_name: String | e.g. ".uk", ".com"
  • domain_contact: Object (required)
    • first_name, last_name, organization, street_address, post_code, city, state: String | at least one of first_name / last_name is required
    • country: String | ISO-2
    • email: String
    • phone: String | E.164 (+CC.NUMBER). A national number such as 0612345678 is converted using country; one that cannot be recognized is rejected
    • extra_properties: Object | TLD-specific registry fields

Update a Domain Contact

PATCH /api/domain_contacts/:id

Returns 200, or 202 with pending_process when the registry processes the update asynchronously. If any currently-associated domain rejects the change, the contact is transparently split (the original keeps the failing domains, a new contact is created for the rest). Pass tld_id/tld_name to override which TLD's validation rules apply (defaults to the first linked registration's TLD).

Params
  • tld_id | tld_name: see create
  • domain_contact: Object | same fields as create (all optional)
Errors
  • 422 domain_import_held | a registration using this contact is on hold

Delete a Domain Contact

DELETE /api/domain_contacts/:id

Only allowed when no registration uses this contact. Returns 204.

Errors
  • 422 contact_in_use | still linked to a registration
  • 422 tld_required_for_orphan | orphan contact + no tld_id/tld_name provided

Resend Verification Email

POST /api/domain_contacts/:id/resend_verification

For contacts on TLDs that require registrant validation (.au, .it, …). Returns { "status": "queued" }.

Errors
  • 422 domain_import_held | a registration using this contact is on hold

Domain Registrations

:id is the registration guid.

Domain Registration shape
  • id: String | guid
  • name: String
  • status: String
  • expires_at: DateTime
  • auto_renew: Boolean
  • locked: Boolean
  • privacy_protect: Boolean
  • dnssec_enabled: Boolean
  • server_transfer_prohibited: Boolean
  • local_contact_active: Boolean
  • cancellation_deadline_at: DateTime | when applicable
  • within_cancellation_window: Boolean | when applicable
  • opt_out_deadline_at: DateTime | null | the deadline for turning auto-renew off with the coming term refunded or credited. Equal to cancellation_deadline_at, except for some domains: turning auto-renew off after it (allowed until cancellation_deadline_at) refunds nothing
  • renewal_invoice_on: Date | null | the day this cycle's renewal is invoiced; null without an expiry or billing plan
  • auto_renew_enable_blocked: Boolean | true when turning auto-renew on is refused with renewal_due; use Renew now instead
  • renew_now_available: Boolean | true when POST .../renew_now can return a payable invoice
  • nameservers: Array<String>
  • tld: Object | { id, name, registrar }
  • owner_contact / admin_contact / tech_contact / billing_contact: Object | see Domain Contact shape, or null
  • pending_async: Boolean
  • rtr_process_id: String
  • rtr_process_status: String
  • transfer_out_pending: Boolean
  • push_transfer_pending: Boolean
  • subscription_id: String
  • feature_flags: Object | { supports_privacy, supports_transfer_lock, supports_push_transfer, supports_dnssec, requires_contact_validation, authcode_behavior }
  • fees: Object | { privacy_enable, registrant_change } — each { amount_cents, currency } or null. Priced only on list and view; every other response that returns a registration reports both as null regardless of the TLD's real fees
  • created_at: DateTime
  • updated_at: DateTime

Every endpoint that returns a registration renders the same envelope. While an registrar process is in flight (pending_async is true) that envelope also carries a pending_process object — on the 202 that opens the process, and on any later response until it clears. It is omitted entirely the rest of the time.

pending_process shape
  • id: String | the registrar process identifier — the same value as rtr_process_id
  • action: String | null | the registrar command that opened the process, e.g. PushTransfer, UpdateContactCommand; null when the endpoint did not label it
  • status: String | the registrar's process status, or pending until one is reported — the same value as rtr_process_status
  • poll_url: String | relative path (not an absolute URL) to this registration's process, e.g. /api/domain_registrations/{id}/processes/{process-id} — this is what a 202 caller polls; see Get a Process

List Domain Registrations

GET /api/domain_registrations

Params (optional)
  • q: String | case-insensitive substring match against name

Returns { "domain_registrations": [ ... ] }.

View a Domain Registration

GET /api/domain_registrations/:id

Adds, when applicable. dns_zone, linked_site and transfer_out are omitted from the JSON entirely when they do not apply — they are never returned as null, so test for the key's presence rather than for a null value:

Returned Params
  • domain_registration: Object | see shape above
  • dns_zone: Object | { id, name } — only when the account has a DnsZone for this name
  • linked_site: Object | { id, name } — only when a Site uses this name as its hostname
  • transfer_out: Object | live registry view, only while transfer_out_pending is true

Check Availability

POST /api/domain_registrations/check

Params
  • domain: String (required) | fully-qualified, e.g. "example.com"
Returned Params
  • domain: String | normalized lookup
  • available: Boolean | true only when the registry says it's available AND a registration price exists for this account — so a name the registry would sell you still reports false when we can't price it
  • premium: Boolean
  • owned_by_account: Boolean
  • reason: String | null | registrar-supplied reason when unavailable
  • price: Object | null | { amount_cents, currency } — current orderable registration price
  • transfer_price: Object | null | { amount_cents, currency } — current orderable transfer-in price

The registration price field is price, not create_price

The registration price is emitted as price; only the transfer price keeps a _price suffix. Both keys are always present; either can be null when there is no price for this account's plan.

Errors
  • 422 missing_domain / invalid_domain / unknown_tld
  • 502 request_failed | the registrar lookup failed or raised. This endpoint does not use registrar_unavailable — every failure path here carries its own code, so request_failed is the only 502 code it emits

Domain Suggestions

POST /api/domain_registrations/suggestions

Params
  • domain: String (required) | base name or fully-qualified
Returned Params
  • domain: String | normalized lookup
  • suggestions: Array<Object>
    • domain: String
    • tld: String
    • source: String | ADAC categorization (e.g. "spinner", "premium")
    • available: Boolean
    • price: Object | { amount_cents, currency }
Errors
  • 422 missing_domain
  • 503 missing_api_key
  • 502 registrar_unavailable

Update a Registration

PATCH /api/domain_registrations/:id

Currently the only supported field is auto_renew.

  • Turning it off before the registry deadline (or, where it differs, before opt_out_deadline_at) refunds money already billed for the coming year (paid invoice) or credits it (unpaid invoice). settlement shows where that stands.
  • Turning it back on before any money has moved cancels that refund (settlement.status is canceled_by_enable) and the renewal invoice stands. After money has moved, it is refused; use Renew now.
Params
  • domain_registration: Object
    • auto_renew: Boolean
Returned Params
  • domain_registration: Object | refreshed
  • scenario: String | enabled, clean_cancel, refund_cancel, or late_cancel
  • settlement: Object | null | the refund for turning auto-renew off. Always present on an auto_renew update (null when there is none)
    • status: String | for example pending, admin_review, approved, failed, missed, settled. After an enable that canceled the refund, the object is only { status: "canceled_by_enable" }
    • refund: String | refunded, credited, voided, pending, under_review, or none
    • refund_cents: Integer | settled amount, or the estimate while the settlement is open
    • credit_cents: Integer | settled amount, or the estimate while the settlement is open
    • currency: String | null | ISO 4217, lowercase
    • waiting: String | null | payment (a bank debit is still clearing), finalize (the renewal invoice is still being issued), or null
Errors
  • 422 invalid_param | auto_renew was sent but is not a boolean
  • 422 cancellation_window_passed | cannot disable auto-renew once the registry deadline has passed
  • 422 auto_renew_settlement_in_progress | a refund for this renewal is being processed; retry once it completes
  • 422 renew_now_payment_processing | a Renew now payment is still clearing; retry once it has cleared
  • 422 renewal_due | this renewal is overdue; use Renew now
  • 422 renewal_price_missing | no renewal price is configured for this domain
  • 422 auto_renew_dunning_locked | an unpaid invoice locks auto-renew off
  • 422 auto_renew_bridged_term_credited | the current term was already refunded or credited; billing resumes at the next term's invoice date
  • 422 auto_renew_import_charge_pending / auto_renew_import_charge_dropped | the domain's one-time charge is unfinished or was dropped; retry after the date in the message
  • 422 auto_renew_update_failed | any other failure
  • 400 no_op | no supported fields in the update

Renew a Domain Now

POST /api/domain_registrations/:id/renew_now

Returns a payable invoice for the domain's current renewal, when renew_now_available is true on the registration. The domain is renewed at the registry once the invoice is paid. Calling it again returns the same open invoice. Requires domains:write and the can_edit role; it is not guarded by 409 registration_busy.

Returned Params
  • payable_url: String | hosted invoice page where the customer pays
  • invoice_id: String | null | the invoice's id at our payment provider
Errors
  • 422 recovery_wrong_phase | Renew now is not available for this domain right now
  • 422 renewal_term_cap | a registration can run at most 10 years ahead
  • 422 recovery_payment_received | the open invoice is already paid and the renewal is being processed
  • 422 renewal_payment_processing | a payment of this domain's open renewal invoice is still processing (for example a SEPA debit). Retry once it has cleared or failed
  • 422 renew_now_failed | the invoice could not be created
  • 422 domain_import_held | the registration is on hold

Update Nameservers

PATCH /api/domain_registrations/:id/nameservers

Params
  • nameservers: Array<String> (required)

Returns 200 or 202 (with pending_process).

Errors
  • 422 nameservers_required | the list is empty / all blank

Toggle Transfer Lock

PATCH /api/domain_registrations/:id/lock

Toggles CLIENT_TRANSFER_PROHIBITED at the registry.

Params
  • locked: Boolean (required)
Errors
  • 422 invalid_param | locked is missing or is not a boolean
  • 422 lock_unsupported | TLD does not support a transfer lock
  • 422 server_transfer_prohibited | registry has prohibited transfers

Toggle WHOIS Privacy

PATCH /api/domain_registrations/:id/privacy

Params
  • privacy_protect: Boolean (required)

Disabling privacy is always free. Enabling on a metered TLD returns 402:

Fee-bearing response (402 Payment Required)
  • errors: Array
  • code: String | payment_required
  • price: Object | { amount_cents, currency, role: "privacy" }
  • portal_url: String
  • remediation: String
Errors
  • 422 invalid_param | privacy_protect is missing or is not a boolean
  • 422 privacy_unsupported | TLD does not support WHOIS privacy

Manage DNSSEC

PATCH /api/domain_registrations/:id/dnssec

Params
  • mode: String (required) | enable, disable, or add_keys
  • key_data: Array<Object> | required for enable / add_keys
    • flags: Integer
    • algorithm: Integer
    • publicKey: String | base64
Errors
  • 422 invalid_mode | mode missing or unknown
  • 422 dnssec_no_keys | enable/add_keys called without key_data

Change Registrant / Holder

PATCH /api/domain_registrations/:id/holder

Either edit the existing owner contact in place, or replace it.

Params
  • holder_contact: Object (required)
    • action_mode: String | edit_current or change
    • first_name, last_name, organization, street_address, post_code, city, state: String
    • country: String | ISO-2
    • email: String
    • phone: String | E.164
    • extra_properties: Object
    • confirm_reverification: "1" | required when edits touch a validated field
  • source_domain_contact_id: Integer | with change, reuse this existing contact
  • new_contact: Object | with change, create a new contact

The fee gate fires only on action_mode: change on a metered TLD (returns 402 payment_required with a price block whose role is registrant_change + portal_url); edit_current edits are always free. To perform the billable change directly (rather than being bounced to the portal), use POST .../registrant_change.

Errors
  • 402 payment_required | action_mode: change on a TLD that meters registrant changes (price role: "registrant_change", fee block + portal_url)
  • 409 reverification_required | validated fields changed without confirm_reverification: "1"
  • 404 source_contact_not_found | source_domain_contact_id not found or unused in this account

Order a Registrant (Holder) Change

POST /api/domain_registrations/:id/registrant_change

Places a paid order to change the registration's registrant (owner) contact — for TLDs that bill registrant changes (e.g. .com / .net via Verisign IRTP). This is the billable counterpart to PATCH .../holder: that endpoint makes free edits and bounces fee-bearing changes to the portal with 402; this one charges the account's default payment method and applies the change asynchronously. Returns the same 202 Accepted order/cart envelope as POST /api/orders — poll the returned order via /api/orders/:id.

OAuth-blocked; needs an order-create user

Not in the domains:write allowlist — OAuth access tokens cannot reach it. Requires a user-scoped credential (orders are owned by a User): a system Account-bearer key returns 401 user_required, and a user lacking order-create permission returns 403 forbidden. Like other mutations, an in-flight registrar process rejects with 409 registration_busy.

Params (provide exactly ONE new-owner source)
  • source_domain_contact_id: Integer | reuse an existing contact owned by the account
  • new_contact: Object | create a new owner contact
    • first_name | last_name: String | at least one is required
    • country (ISO-2), email, phone: required. Phone is E.164 +CC.NUMBER; a national number such as 0612345678 is converted using country
    • organization, street_address, post_code, city, state: String | optional
    • extra_properties: Object | optional, TLD-specific registry fields

Returns 202 with the order/cart envelope.

Errors
  • 401 user_required | system Account-bearer key (no user)
  • 403 forbidden | user lacks order-create permission
  • 403 trial_account | trial accounts cannot order
  • 409 registration_busy | a registrar process is already in flight
  • 400 no_default_payment_method | no saved default payment method to charge. Checked before anything is built, so nothing is created and nothing is charged
  • 400 billing_details_incomplete | the paying account's billing contact is incomplete
  • 403 billing_permission_required | the user cannot manage billing on the paying account
  • 409 bank_transfer_in_progress | an earlier order of the payer never completed; contact support
  • 409 bank_transfer_busy | another order of the payer is being placed; retry in a few seconds
  • 422 outstanding_balance_exceeded | the payer is over its outstanding-balance limit; pay the open invoices
  • 422 recent_dispute | a returned payment or chargeback in the last 90 days
  • 422 bank_transfer_refused | the order cannot be invoiced for bank transfer
  • 422 bank_transfer_failed | the order stopped after it was invoiced. Do not retry; contact support
  • 422 source_contact_not_found | source_domain_contact_id not found (note: 422 here vs 404 on /holder)
  • 422 contact_invalid | new_contact missing required fields or registry-rejected (includes violations)
  • 422 no_registrant_change_price | no registrant-change price configured for this account/TLD
  • 422 cart_pay_failed | payment could not be initiated (any contact created for the order is removed)
  • 422 domain_import_held | the registration is on hold

It can also answer 409 postpay_busy and 422 in_flight_limit_exceeded, payer_in_dunning, instant_payment_method_required, postpay_route_changed, postpay_failed and the postpay_* blocked refusals postpay_pay_open_invoices, postpay_contact_support and postpay_payment_in_progress; see Orders.

Update Role Contacts

PATCH /api/domain_registrations/:id/contacts

Set admin / tech / billing role contacts (the holder is changed via /holder). Each role is independently optional. For each present role choose one source:

  • {role}_contact: { source: "same_as_owner" }
  • {role}_contact: { source: "existing" } + {role}_source_domain_contact_id: <id>
  • {role}_contact: { source: "new" } + {role}_new_contact: { ...fields... }
Errors
  • 422 owner_contact_missing | same_as_owner used with no owner contact set

Retrieve the EPP / Auth Code

GET /api/domain_registrations/:id/epp_code

Requires the domains:write scope despite being a GET. Returns { "authcode": "..." }.

Errors
  • 422 server_transfer_prohibited | registry has prohibited transfers
  • 422 authcode_unavailable | TLD hides the authcode (authcode_behavior: hidden)
  • 422 domain_import_held | registration is on hold
  • 502 authcode_unavailable | registrar failed to return the authcode

Force Re-Sync

POST /api/domain_registrations/:id/force_sync

Re-reads the domain from the registrar and syncs local state.

Returned Params
  • domain_registration: Object | refreshed
  • changed: Array<String> | field names that changed

Resolve a Pending Outbound Transfer

POST /api/domain_registrations/:id/transfer_out

Params
  • decision: String (required) | approve or reject
Errors
  • 422 no_pending_transfer_out
  • 422 invalid_decision

Push Transfer to Another Provider

POST /api/domain_registrations/:id/push_transfer

Registrar-to-registrar push transfer (no authcode). Returns 200 or 202.

Params
  • recipient: String (required) | destination registrar handle (e.g. "REG-IDS")
Errors
  • 422 | the registrar rejected the push transfer — the TLD does not support one, one is already in progress, or the domain is not transferable

This endpoint returns no error code

A rejected push transfer answers 422 with an errors array and no code key at all, so there is no machine-readable identifier to branch on. Treat any 422 here as a single "push transfer rejected" outcome and surface the errors text; do not match on push_transfer_unsupported, push_transfer_in_progress or domain_not_transferable — those strings are never sent.

Resend Holder Contact Verification

POST /api/domain_registrations/:id/resend_contact_verification

For TLDs requiring registrant contact verification. Returns { "status": "queued" }.

Errors
  • 422 verification_not_applicable | TLD doesn't require validation, or no owner contact

Hosts (Glue Records)

Glue records for a registration. Nested under /api/domain_registrations/:domain_registration_id/hosts. The route param is :host_name.

List Hosts

GET .../hosts

Returned Params
  • hosts: Array<Object>
    • host_name: String | e.g. "ns1.example.com"
    • addresses: Array<Object>
      • address: String | IP literal
      • version: Integer | 4 or 6

Create a Host

POST .../hosts

The hostname must be a subdomain of the registration. Each address is auto-classified as IPv4/IPv6. Returns 201 { "host": { ... } }.

Params
  • host_name: String (required) | fully-qualified subdomain
  • addresses: Array<Object> (required, at least one)
    • address: String | IP literal (no CIDR)

Update a Host's Addresses

PATCH .../hosts/:host_name

Replaces the address set. Returns 200.

Params
  • addresses: Array<Object> (required) | same shape as create

Delete a Host

DELETE .../hosts/:host_name

Returns 204.


Processes

Registrar processes attached to a registration — every async registrar operation opens one. Poll these after a 202. Nested under /api/domain_registrations/:domain_registration_id/processes.

List Processes

GET .../processes

Returns { "processes": [ ... ] }, newest first (raw registrar process records).

Get a Process

GET .../processes/:id

Returned Params
  • process: Object | raw registrar process body
  • log: Array<Object>

A process whose identifier doesn't belong to the registration returns 404.

Errors
  • 503 registrar_unavailable | no registrar is configured for this TLD
  • 502 process_unavailable | the registrar could not return the process

Resume a Suspended Process

POST .../processes/:id/resend

Returns { "status": "queued" }.

Cancel a Process

DELETE .../processes/:id/cancel

Returns { "status": "cancelled" }.