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



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

<Mermaid
  chart="
graph TD
A[Search availability] --> B[Get registration quote]
B --> C[Execute registration]
C --> D[Poll until complete]
D --> E[Add DNS records]
E --> F[Verify DNS propagation]

style A fill:#e3f2fd
style F fill:#c8e6c9
"
/>

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

<Callout type="info" title="Note">
  If `available` is `true`, proceed to quoting. If `false`, use the suggestions endpoint to find alternatives.
</Callout>

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.

<Callout type="warning">
  Registration applies charges to your payment profile and not reversible. Verify the domain name and quoted price before executing.
</Callout>

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