Make your first call

Overview

This guide walks through making GET /v3/domains/check-availability against the production API. The call is read-only and doesn't require domains to already be registered to your account.

Prerequisites

Before calling the Domains API, you need:

• a GoDaddy account
• a Personal Access Token (PAT) with the appropriate scopes
  Note

  Go to Authenticate to generate a PAT.

• a terminal with curl (macOS, Linux, or WSL)
• Optional: the beta gddy CLI, if you prefer CLI workflows. Go to Set up the CLI.

Set the credential as an environment variable

The PAT is passed as a Bearer token in the Authorization header on every request. Exporting it as an environment variable keeps it out of your shell history and lets you reference it directly in commands without retyping.

• Export the credential:

export GODADDY_PAT="<YOUR_GODADDY_PAT>"

Make the call

GET /v3/domains/check-availability takes a single domain query parameter and returns whether that domain can be registered, along with current pricing for each registration term. The request is read-only, so no charges apply.

• Run the request:

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

const pat = process.env.GODADDY_PAT;
const res = await fetch(
  "https://api.godaddy.com/v3/domains/check-availability?domain=your-idea.com",
  {
    headers: {
      Authorization: "Bearer " + pat,
    },
  }
);
const result = await res.json();
console.log(result);

import os, requests

pat = os.environ["GODADDY_PAT"]
res = requests.get(
    "https://api.godaddy.com/v3/domains/check-availability",
    params={"domain": "your-idea.com"},
    headers={
        "Authorization": "Bearer " + pat,
    },
)
print(res.json())

Read the response

The API returns a JSON object describing availability and current pricing. available tells you whether the domain can be registered right now. prices[] contains one entry per registration term. price.value and renewalPrice.value are expressed in the smallest currency unit, such as cents for USD. Divide by 100 when displaying USD prices.

• Check that your output matches this shape:

{
  "available": true,
  "definitive": false,
  "domain": "your-idea.com",
  "inventory": "REGISTRY",
  "prices": [
    {
      "period": 1,
      "price": {
        "currencyCode": "USD",
        "value": 1199
      },
      "renewalPrice": {
        "currencyCode": "USD",
        "value": 2299
      },
      "term": "YEAR"
    },
    {
      "period": 2,
      "price": {
        "currencyCode": "USD",
        "value": 3098
      },
      "renewalPrice": {
        "currencyCode": "USD",
        "value": 4598
      },
      "term": "YEAR"
    }
  ]
}

The API may return more prices[] entries for additional periods. Availability and pricing are indicative; the final price is locked when you create a registration quote.

Common errors

Go to Handle errors for the full error envelope reference, status code semantics, and retry guidance.

Next steps

Where you go from here depends on what you're trying to do. If you already own domains at GoDaddy, the most common next call is GET /v1/domains which lists the domains on your account (covered in Manage existing domains). If you want to acquire new domains, start with search and registration (covered in Search for domains).

Last updated on