# About the Domains API (https://developer.godaddy.com/en/docs/api-users/domains)

***

title: About the Domains API
description: How the Domains API is structured, what its version namespaces cover, and how the core resources relate to each other.
related:
concepts:

* title: "Domain management concepts"
  href: "/docs/api-users/concepts/domain-management-concepts"
* title: "How GoDaddy APIs work"
  href: "/docs/api-users/concepts/how-godaddy-apis-work"
  guides:
* title: "Search domain availability"
  href: "/docs/api-users/domains/search"
* title: "Register a domain"
  href: "/docs/api-users/domains/register"
* title: "Manage DNS records"
  href: "/docs/api-users/domains/manage/dns"

***

## 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](https://developer.godaddy.com/docs/api-users/concepts/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: `renewAuto` flag and `expires` timestamp

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](https://developer.godaddy.com/docs/api-users/domains/search)      |
| Get suggestions           | v3      | [Search domain availability](https://developer.godaddy.com/docs/api-users/domains/search)      |
| Register a domain         | v3      | [Register a domain](https://developer.godaddy.com/docs/api-users/domains/register)             |
| List registered domains   | v1      | [Registered domains](https://developer.godaddy.com/docs/api-users/domains/manage/list)         |
| Manage DNS records        | v3      | [Manage DNS records](https://developer.godaddy.com/docs/api-users/domains/manage/dns)          |
| Replace nameservers       | v3      | [Manage DNS records](https://developer.godaddy.com/docs/api-users/domains/manage/dns)          |
| Update WHOIS contacts     | v1      | [Update contacts](https://developer.godaddy.com/docs/api-users/domains/manage/update-contacts) |
| Toggle auto-renew / renew | v1      | [Manage renewals](https://developer.godaddy.com/docs/api-users/domains/manage/renewals)        |
| Toggle registry lock      | v1      | [Lock a domain](https://developer.godaddy.com/docs/api-users/domains/manage/lock)              |
| Configure forwarding      | v2      | [Forward a domain](https://developer.godaddy.com/docs/api-users/domains/manage/forwarding)     |
| Transfer a domain in      | v2      | [Browse the Domains API](https://developer.godaddy.com/docs/api-users/domains/manage)          |

## 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                               |