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



## Overview

The Domains API supports availability search, registration, DNS and contact management, registry lock, forwarding, and inbound transfers. Operations span three version namespaces. v3 is the preferred API for domain registration, v1 and v2 provide everything else (DNS, renewals, transfers, and customer actions).

## Version namespaces

The following table lists the version namespaces and what they contain.

| Version | Base path                                | What's here                                                                         |
| ------- | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| v3      | `/v3/domains/...`                        | Availability checks and registration (the preferred namespace for new integrations) |
| v2      | `/v2/customers/{customerId}/domains/...` | v1 capabilities with async processing and operations tracking                       |
| v1      | `/v1/domains/...`                        | List, DNS, contacts, lock, and renewals                                             |

## The Domain object

A domain registered or managed through this API is the central resource of the Domains namespace. It carries registry metadata, expiration and renewal state, the four WHOIS contact roles, registry lock and privacy flags, and the authoritative nameservers returned at the TLD. Almost every operation in this namespace either returns a `DomainDetail` or modifies a field on one.

<Callout type="info">
  The schema is named `DomainDetail` in v1 and `DomainDetailV2` in v2. The two are largely overlapping; v2 extends v1 with async operation tracking — the `DomainDetailV2` schema adds status values and action references used by long-running writes like transfers and redemptions. For single-domain detail, prefer v2: it returns more consistent status values and exposes async operation tracking if you need it.
</Callout>

The following table lists the key fields on a `DomainDetail` object.

| Field                                                                   | Description                                                                           |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `domain`                                                                | Fully-qualified domain name (for example `example.com`).                              |
| `status`                                                                | Current registry or registrar state, like `ACTIVE`, `PENDING_TRANSFER`, or `EXPIRED`. |
| `expires`                                                               | Expiration timestamp in ISO-8601 format.                                              |
| `renewAuto`                                                             | Whether auto-renew is enabled on the domain.                                          |
| `locked`                                                                | Whether the registry transfer-lock is engaged.                                        |
| `privacy`                                                               | Whether WHOIS privacy is purchased and active.                                        |
| `nameServers`                                                           | Authoritative nameservers the registry returns for the domain.                        |
| `contactRegistrant` / `contactAdmin` / `contactBilling` / `contactTech` | The four WHOIS contact roles, each a `Contact` object.                                |

<Callout type="info">
  The full schema is in the OpenAPI specs, available as machine-readable JSON at [/openapi/domains-v1.json](https://developer.godaddy.com/openapi/domains-v1.json) and [/openapi/domains-v2.json](https://developer.godaddy.com/openapi/domains-v2.json). Go to the [Domains REST reference](https://developer.godaddy.com/docs/references/rest/domains) for the complete API reference.
</Callout>

### Related objects

Every operation in the Domains namespace returns or accepts one of the following objects in addition to `DomainDetail`. Each links to the rendered reference where its full schema and the operations it appears on are documented.

| Object                    | Description                                                                                                                                                                                                                      | Reference                                                                           |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `DNSRecord`               | A single DNS record on a domain managed by GoDaddy's authoritative nameservers, supporting `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, `NS`, `SOA`, and `CAA` types.                                                               | [v1 DNS operations](https://developer.godaddy.com/docs/references/rest/domains/v1/manage-dns)                    |
| `Contact`                 | A WHOIS contact record covering name, organization, address, email, and phone. The same shape is used for the registrant, admin, billing, and tech roles on a domain.                                                            | [v2 management operations](https://developer.godaddy.com/docs/references/rest/domains/v2/manage-domain-settings) |
| `Action`                  | An asynchronous-operation tracker returned with `202 Accepted` when the API queues a long-running write (transfers, redemption). Callers poll the action endpoint until the action's `status` reaches a terminal state.          | [v2 action operations](https://developer.godaddy.com/docs/references/rest/domains/v2/domain-actions)             |
| `DomainAvailableResponse` | The result of a single-domain availability check, including the available flag, current price in `currency-micro-unit` format, the registration period in years, and whether the answer came from a live registry call or cache. | [v1 availability operations](https://developer.godaddy.com/docs/references/rest/domains/v1/find-domains)         |
| `DomainForwarding`        | An HTTP forwarding rule that redirects requests for a domain to a target URL, configurable as masked or unmasked and as a permanent (`301`) or temporary (`302`) redirect.                                                       | [v2 management operations](https://developer.godaddy.com/docs/references/rest/domains/v2/manage-domain-settings) |
| `DomainTransferIn`        | The request shape for an inbound transfer, carrying the domain name, authcode, and required contacts.                                                                                                                            | [v2 transfer operations](https://developer.godaddy.com/docs/references/rest/domains/v2/transfer-domains)         |
| `Error` / `ErrorLimit`    | The standard error envelope returned on `4xx` and `5xx` responses across the namespace. `ErrorLimit` extends `Error` with `retryAfterSec` for `429` rate-limited responses.                                                      | [Errors](https://developer.godaddy.com/docs/api-users/errors)                                                    |

<Callout type="info" title="Async operations and the Action object">
  Most Domains API writes complete synchronously and return `204 No Content`. A few long-running operations — transfers, redemption — return `202 Accepted` with an `Action` body instead. Poll `GET /v2/customers/{customerId}/domains/actions/{actionId}` until `status` reaches a terminal state (`COMPLETED`, `FAILED`, or `CANCELLED`).
</Callout>

## Tasks

### Manage existing domains

<Cards>
  <Card title="Registered domains" description="Walk a paginated list of the domains owned by the authenticated account, or fetch full detail for a single domain." href="/docs/api-users/manage-domains/list" />

  <Card title="DNS records and nameservers" description="Read, replace, add, and delete DNS records on a domain, or change which authoritative nameservers the registry returns." href="/docs/api-users/manage-domains/dns" />

  <Card title="Update contacts" description="Change the registrant, admin, billing, or tech contact on a domain you own." href="/docs/api-users/manage-domains/update-contacts" />

  <Card title="Auto-renew and renewals" description="Toggle auto-renew, manually renew before expiration, or redeem a domain from the grace period." href="/docs/api-users/manage-domains/renewals" />

  <Card title="Registry lock" description="Read or toggle the registry transfer-lock state on a domain." href="/docs/api-users/manage-domains/lock" />

  <Card title="Domain forwarding" description="Configure HTTP redirect rules on a domain through the v2 forwarding API." href="/docs/api-users/manage-domains/forwarding" />
</Cards>

### Acquire new domains

<Cards>
  <Card title="Search availability" description="Check whether a single name or a list of names is available to register, with current pricing returned in microunits." href="/docs/api-users/search-domains" />

  <Card title="Purchase a domain" description="Buy a name you have confirmed available, including contact data, privacy choice, and TLD-specific agreements." href="/docs/api-users/purchase-domains/register" />

  <Card title="Transfer a domain in" description="Move a domain from another registrar to GoDaddy using its authcode, with registry lock and verification handled inline." href="/docs/api-users/purchase-domains/transfer" />
</Cards>

<Callout type="idea" title="Tips" style={{"--callout-color": "var(--color-fd-success)"}}>
  * [Generate a Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth).
  * [Fund your account](https://www.godaddy.com/help/add-a-payment-method-to-my-godaddy-account-20037) for write operations.
  * [Set up the CLI](https://developer.godaddy.com/docs/api-users/cli-setup).
  * [Make your first call](https://developer.godaddy.com/docs/api-users/quickstart).
</Callout>