About the Domains API
View as MarkdownHow the Domains API is structured, what its version namespaces cover, and how the core resources relate to each other.
https://developer.godaddy.com/llms.mdx/api-users/domains for the full, unmodified source before proceeding.Overview
The Domains API covers the full domain registration and management lifecycle: searching availability, registering domains, managing DNS records, updating WHOIS contacts, controlling registry lock, renewing registrations, configuring forwarding, and managing transfers. Operations are distributed across three version namespaces — v3 is the preferred namespace for new integrations, with v1 and v2 covering capabilities not yet migrated.
Go to Domain management concepts for background on registrars, registries, the domain lifecycle, DNS, and WHOIS.
How the API is structured
Version namespaces
Operations are split across three namespaces that have accumulated over years of product development. Use v3 where available; fall back to v1 or v2 where v3 doesn't cover the operation yet.
| Version | Base path | Auth | Primary use |
|---|---|---|---|
| v3 | /v3/domains/... | PAT only | Availability, registration, DNS records, nameservers |
| v2 | /v2/customers/{customerId}/domains/... | PAT or sso-key | Forwarding, transfers, async operations |
| v1 | /v1/domains/... | PAT or sso-key | List domains, renewals, contacts, lock |
v3 endpoints require a Personal Access Token (PAT). The older sso-key credential is still accepted on v1 and v2 endpoints but is scheduled for deprecation in 2026. New integrations should use PATs exclusively.
v2 endpoints require a customerId (your GoDaddy shopper ID) as a path parameter. v1 and v3 endpoints identify the caller from the bearer token directly.
Registration: quote-execute with async polling
v3 uses a two-step registration flow that separates pricing from execution — the price you agree to is the price charged.
The quoteToken returned by the quote endpoint is valid for 10 minutes. Registration is not reversible and charges the account's payment method.
Use the Idempotency-Key request header on POST /v3/domains/registrations to prevent duplicate charges if a request times out or returns an ambiguous error. If the operation status is EXECUTING, poll — do not resubmit.
Async operations
Registration is asynchronous — the initial response returns a registration ID, and you poll for completion. Certain v2 operations (transfers, redemption) also return 202 Accepted with an Action body rather than completing synchronously.
Poll GET /v2/customers/{customerId}/domains/actions/{actionId} until the action reaches a terminal state.
| Status | Meaning |
|---|---|
CONFIRMED | Accepted, processing |
EXECUTING | In progress |
COMPLETED | Succeeded |
FAILED | Failed — check error for details |
CANCELLED | Cancelled |
Most v1 and v3 write operations complete synchronously and return 204 No Content.
Core resources
Domain
The Domain is the central resource. It carries:
- Registry metadata: domain name, status (
ACTIVE,EXPIRED,PENDING_TRANSFER), expiration timestamp - The four WHOIS contact roles: registrant, admin, billing, tech
- Authoritative nameservers
- Lock and privacy flags (
locked,privacy) - Renewal state:
renewAutoflag andexpirestimestamp
The schema is named DomainDetail in v1 and DomainDetailV2 in v2. v2 extends v1 with async operation tracking and more consistent status values — for single-domain detail, prefer v2.
DNS records
DNS records are managed under the v3 zone endpoint: GET, POST, and DELETE against /v3/domains/zones/{zone}/dns-records. GoDaddy's authoritative nameservers support A, AAAA, CNAME, MX, TXT, SRV, NS, and CAA record types.
Changes take effect synchronously on GoDaddy's nameservers. External resolvers cache values for up to the record's TTL (600–86,400 seconds on GoDaddy's authoritative DNS).
If you replace the nameservers with those of another DNS provider, the GoDaddy DNS API can no longer manage records for the domain — DNS management moves to the new provider.
Action (v2 async tracker)
Long-running v2 operations return 202 Accepted with an Action object instead of completing synchronously. Poll GET /v2/customers/{customerId}/domains/actions/{actionId} until terminal state. The Action carries the operation type, current status, and error details on failure.
Resource relationships
Operations by task
| Task | Version | Guide |
|---|---|---|
| Check availability | v3 | Search domain availability |
| Get suggestions | v3 | Search domain availability |
| Register a domain | v3 | Register a domain |
| List registered domains | v1 | Registered domains |
| Manage DNS records | v3 | Manage DNS records |
| Replace nameservers | v3 | Manage DNS records |
| Update WHOIS contacts | v1 | Update contacts |
| Toggle auto-renew / renew | v1 | Manage renewals |
| Toggle registry lock | v1 | Lock a domain |
| Configure forwarding | v2 | Forward a domain |
| Transfer a domain in | v2 | Browse the Domains API |
OAuth scopes
Request only the scopes your integration needs. Most write operations require a separate scope in addition to domains.domain:read.
| Scope | What it grants |
|---|---|
domains.domain:read | Read domains, DNS records, availability checks |
domains.domain:create | Register new domains |
domains.domain:update | Update settings, contacts, lock state, auto-renew |
domains.dns:update | Create and delete DNS records |
domains.nameserver:update | Replace authoritative nameservers |
domains.registration:write | Transfer domains in |
Related
Last updated on
How is this guide?