Get Started with NameGrid: Register Your First Domain

This guide walks you through everything you need to go from zero to a registered domain using the NameGrid API. By the end you’ll have an API key, you’ll know how to check whether a domain is available, and you’ll have registered your first domain — all from the command line.

Create an API key

Every request to the NameGrid API must include an API key. To generate one:

Sign in to your dashboard at app.namegrid.org.
Go to Settings → API tokens.
Click Create token, give it a descriptive name (e.g. my-first-key), and confirm.
Copy the key immediately — it is displayed only once.

Your key looks like this:

ng_live_xxxxxxxxxxxxxxxxxxxxxxxx

NameGrid stores only a hash of your API key, not the raw value. If you lose your key, revoke it from the dashboard and create a new one.

Check domain availability

Before registering, confirm the domain you want is available. Send a POST request to /v1/domains/check with a list of domain names:

curl -X POST https://api.namegrid.org/v1/domains/check \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["example.com", "example.net"]}'

Response:

{
  "results": [
    { "domain": "example.com", "available": true, "isPremium": false },
    { "domain": "example.net", "available": false, "isPremium": false }
  ]
}

Each result tells you whether the domain is available and whether it carries a premium price. Only proceed to registration with domains where "available": true.

Once you’ve confirmed availability, register the domain with a POST to /v1/domains. Include a contact object with the registrant’s details — this is required by ICANN for all new registrations.

NameGrid uses a credit-based billing model where 1 credit = $1. Make sure your account has enough credits before registering. Check your balance in the dashboard or via the Account API.

curl -X POST https://api.namegrid.org/v1/domains \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "years": 1,
    "autoRenew": true,
    "privacyEnabled": true,
    "contact": {
      "firstName": "Jane",
      "lastName": "Doe",
      "organization": "Acme Inc",
      "email": "jane@example.com",
      "phone": "+1.5555550123",
      "address1": "123 Main St",
      "city": "Springfield",
      "stateProvince": "IL",
      "postalCode": "62704",
      "country": "US"
    }
  }'

Response:

{
  "domain": {
    "name": "example.com",
    "status": "active",
    "autoRenew": true,
    "privacyEnabled": true,
    "years": 1,
    "creditsCharged": 12,
    "expiresAt": "2027-01-04T12:00:00.000Z",
    "createdAt": "2026-01-04T12:00:00.000Z"
  }
}

The creditsCharged field confirms how many credits were deducted. The domain is active immediately — you can start managing DNS records right away.

List your domains

To see all domains registered under your workspace, send a GET request to /v1/domains:

curl https://api.namegrid.org/v1/domains \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx"

The response returns a list of your domains with their status, expiry dates, and renewal settings. Use this endpoint to build dashboards, trigger renewal reminders, or audit your portfolio.

Next steps

You’ve registered your first domain — here’s where to go from here:

Manage DNS records — add A, CNAME, MX, and TXT records to your domain.
Renew a domain — manually renew or verify auto-renewal is configured.
Authentication — learn about API key security, workspace scope, and rate limits.
API Reference — explore every available endpoint with full parameter documentation.

Get Started

Core Concepts

Guides

Get Started with NameGrid: Register Your First Domain

Next steps

​Next steps

Next steps