# How to register and configure a domain (https://developer.godaddy.com/en/docs/api-users/domains/workflows/domain-lifecycle)

***

title: How to register and configure a domain
description: End-to-end workflow — search for a domain, register it, configure DNS, and verify the setup.
keywords: domain lifecycle, availability check flow, quote execute flow, buy configure domain, Idempotency-Key header, poll registration, configure DNS after registration
agentNotes:
permissions: \["Domain Registration", "DNS Management"]
scopes: \["domains.domain:read", "domains.domain:create", "domains.dns:update"]
rateLimit: "Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values."
idempotent: false
destructive: false
failureRecovery: "Registration charges the account and is not reversible. Use the Idempotency-Key header on POST /v3/domains/registrations to prevent duplicate charges. If a step fails mid-workflow, poll the operation URL before retrying the registration step. DNS writes are safe to retry."
related:
apis:

* title: "v3 Registrations"
  href: "/docs/references/rest/domains/v3/registrations"
* title: "v3 Registration Quotes"
  href: "/docs/references/rest/domains/v3/registration-quotes"
  guides:
* title: "Quickstart"
  href: "/docs/api-users/quickstart"
* 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"
* title: "Set up a payment profile"
  href: "/docs/api-users/payment-profile"
* title: "Authentication"
  href: "/docs/api-users/auth"
* title: "Handle errors"
  href: "/docs/api-users/errors"
* title: "Handle rate limits"
  href: "/docs/api-users/rate-limits"

***

## Overview

This workflow walks through the complete domain lifecycle from search to live configuration. By the end, you'll have a registered domain with DNS records serving traffic. Code examples are available in curl, Node, Python, and Go.

## Prerequisites

The following prerequisites are required before you register and configure a domain:

* A GoDaddy account with a [payment profile](https://developer.godaddy.com/docs/api-users/payment-profile) configured
* A [Personal Access Token](https://developer.godaddy.com/docs/api-users/auth) with `domains.domain:read`, `domains.domain:create`, and `domains.dns:update` scopes, exported as `GODADDY_PAT`; also export `BASE=https://api.godaddy.com` for the multi-language examples
* A terminal with `curl`, or Node.js, Python, or Go

## Search for an available domain

The following procedure checks whether your desired domain is available for registration.

1. Check availability:

```bash tab="curl"
curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com" \
  -H "Authorization: Bearer $GODADDY_PAT"
```

```bash tab="CLI"
gddy domain available your-idea.com
```

If `available` is `true`, proceed to quoting. If `false`, use the suggestions endpoint to find alternatives.

2. Get suggestions:

```bash tab="curl"
curl -s "https://api.godaddy.com/v3/domains/suggestions?query=your+idea&tlds=com,net,io&pageSize=10" \
  -H "Authorization: Bearer $GODADDY_PAT"
```

```bash tab="CLI"
gddy domain suggest "your idea" --tlds com --tlds net --tlds io --limit 10
```

Go to [Search domain availability](https://developer.godaddy.com/docs/api-users/domains/search) for the full parameter reference.

## Get a registration quote

The following procedure locks in a price by requesting a quote. The `quoteToken` in the response is valid for 10 minutes.

1. Request a quote:

```bash tab="curl"
curl -s -X POST "https://api.godaddy.com/v3/domains/registration-quotes" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "your-idea.com",
    "period": 1
  }'
```

```bash tab="CLI"
gddy domain quote your-idea.com
```

2. Note the `quoteToken` and `requiredAgreements` from the response — you'll need both for the next step. The GoDaddy CLI stores the token and handles agreement acceptance automatically through `--agree`.

## Execute the registration

The following procedure submits the registration using the quote token and ICANN consent.

Registration applies charges to your payment profile and is not reversible. Verify the domain name and quoted price before executing.

* Submit the registration:

```bash tab="curl"
curl -s -X POST "https://api.godaddy.com/v3/domains/registrations" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "quoteToken": "<QUOTE_TOKEN>",
    "domain": "your-idea.com",
    "period": 1,
    "consent": {
      "agreedAt": "2026-01-15T10:30:00.000Z",
      "agreementTypes": ["API_DPA"]
    }
  }'
```

```bash tab="CLI"
# Run without --agree first to review required agreements, then add --agree to confirm.
gddy domain purchase your-idea.com --agree --confirm
```

Go to [Register a domain](https://developer.godaddy.com/docs/api-users/domains/register) for the full field reference and error handling.

## Poll until complete

The following procedure polls the registration status. Registration is asynchronous. Poll the returned operation URL until the status reaches a terminal state. The following table lists the possible statuses:

| Status      | Meaning                                         |
| ----------- | ----------------------------------------------- |
| `CONFIRMED` | Accepted, processing. Keep polling.             |
| `EXECUTING` | In progress. Keep polling.                      |
| `COMPLETED` | Registration succeeded.                         |
| `FAILED`    | Registration failed. Check `error` for details. |

The GoDaddy CLI polls automatically after `gddy domain purchase` and exits when registration reaches a terminal state. No manual polling required.

* Poll the registration:

```bash
curl -s "$BASE/v3/domains/registrations/<REGISTRATION_ID>" \
  -H "Authorization: Bearer $GODADDY_PAT"
```

## Add DNS records

The following procedure adds DNS records to point the domain at your infrastructure. Run these after registration completes.

1. Add an A record for the apex:

```bash tab="curl"
curl -s -X POST "https://api.godaddy.com/v3/domains/zones/your-idea.com/dns-records" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Content-Type: application/json" \
  -d '{ "type": "A", "name": "@", "data": "192.0.2.1", "ttl": 600 }'
```

```bash tab="CLI"
gddy dns add your-idea.com --type A --name @ --data 192.0.2.1 --ttl 600
```

2. Add additional records as needed (CNAME for `www`, MX for email, TXT for verification):

```bash tab="curl"
curl -s -X POST "https://api.godaddy.com/v3/domains/zones/your-idea.com/dns-records" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Content-Type: application/json" \
  -d '{ "type": "CNAME", "name": "www", "data": "your-idea.com", "ttl": 600 }'
```

```bash tab="CLI"
gddy dns add your-idea.com --type CNAME --name www --data your-idea.com --ttl 600
```

Go to [Manage DNS records](https://developer.godaddy.com/docs/api-users/domains/manage/dns) for the full record type reference.

## Verify DNS propagation

The following procedure verifies that your DNS records were created and are propagating.

* List your records to confirm they were created:

```bash tab="curl"
curl -s "https://api.godaddy.com/v3/domains/zones/your-idea.com/dns-records" \
  -H "Authorization: Bearer $GODADDY_PAT"
```

```bash tab="CLI"
gddy dns list your-idea.com
```

DNS changes propagate within minutes for GoDaddy-hosted nameservers. External resolvers may cache the old state for up to the previous TTL value.