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

***

title: Register and configure a domain
description: End-to-end workflow — search for a domain, register it, configure DNS, and verify the setup.
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: "Search domain availability"
  href: "/docs/api-users/search-domains"
* title: "Register a domain"
  href: "/docs/api-users/purchase-domains/register"
* title: "Manage DNS records"
  href: "/docs/api-users/manage-domains/dns"
* title: "Set up a payment profile"
  href: "/docs/api-users/payment-profile"

***

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

## 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` in your environment
* A terminal with `curl`

## Search for an available domain

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

1. Check availability:

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

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

2. Get suggestions:

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

Go to [Search domain availability](https://developer.godaddy.com/docs/api-users/search-domains) 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
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
  }'
```

2. Note the `quoteToken` and `requiredAgreements` from the response (you'll need both for registration).

## Execute the registration

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

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

* Submit the registration:

```bash
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"]
    }
  }'
```

Go to [Register a domain](https://developer.godaddy.com/docs/api-users/purchase-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. |

* Poll the registration:

```bash
curl -s "https://api.godaddy.com/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
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 }'
```

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

```bash
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 }'
```

Go to [Manage DNS records](https://developer.godaddy.com/docs/api-users/manage-domains/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
curl -s "https://api.godaddy.com/v3/domains/zones/your-idea.com/dns-records" \
  -H "Authorization: Bearer $GODADDY_PAT"
```

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