Register a Domain with NameGrid: Step-by-Step Guide

Registering a domain through NameGrid takes just a few API calls. This guide walks you through checking availability, verifying your credit balance, submitting a registration with full contact details, and confirming that your domain is active.

Check domain availability

Before registering, confirm that the domain you want is available. Send a POST request to /v1/domains/check with a list of up to 20 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": ["yourdomain.com", "yourdomain.net"]}'

Response

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

Each result includes two fields:

available — true if the domain is unregistered and can be purchased, false if it is already taken.
isPremium — true if the registry considers this a premium name and charges an elevated price. Check the pricing before proceeding.

Ensure you have enough credits

NameGrid deducts credits from your account balance at registration time. Retrieve your current balance with a GET request to /v1/account.

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

If your balance is too low, top it up at https://app.namegrid.org before continuing. Each credit is worth $1 USD.

Submit a POST request to /v1/domains with your desired domain name, registration options, and full contact information.

curl -X POST https://api.namegrid.org/v1/domains \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "yourdomain.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",
      "address2": "",
      "city": "Springfield",
      "stateProvince": "IL",
      "postalCode": "62704",
      "country": "US"
    }
  }'

Response

{
  "domain": {
    "name": "yourdomain.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 response confirms how many credits were deducted (creditsCharged) and when the registration expires (expiresAt).

If the domain already has an active or pending registration, the API returns a 409 Conflict error. You cannot register a domain that is already taken or being processed.

Registrations are non-refundable once the order is placed. Double-check the domain name and registration period before submitting.

Verify registration

Confirm that your domain is live by fetching its details with GET /v1/domains/yourdomain.com.

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

A successfully registered domain returns a status of active. If the status shows failed, the registration did not complete — check your credit balance and the domain name, then try again. Poll the endpoint periodically after submitting until status changes to active.

Contact information requirements

The contact object is required for every domain registration. The table below describes each field.

Field	Required	Description
`firstName`	Yes	Registrant’s first name.
`lastName`	Yes	Registrant’s last name.
`organization`	Yes	Company or organization name.
`email`	Yes	Contact email address. Used for domain-related notifications.
`phone`	Yes	Phone number in E.164 format with a period separator, e.g. `+1.5555550123`.
`address1`	Yes	Primary street address.
`address2`	Yes	Secondary address line (suite, apartment, etc.). Pass an empty string if not applicable.
`city`	Yes	City name.
`stateProvince`	Yes	State or province code, e.g. `IL` for Illinois.
`postalCode`	Yes	Postal or ZIP code.
`country`	Yes	Two-letter country code following ISO 3166-1 alpha-2, e.g. `US`, `GB`, `DE`.

Additional registration options

years — How long to register the domain. Defaults to 1. Accepts values from 1 to 10.
autoRenew — Set to true to automatically renew the domain before it expires. Requires a sufficient credit balance at renewal time.
privacyEnabled — Set to true to enable WHOIS privacy protection, which replaces your personal contact information in the public WHOIS database with NameGrid proxy details.

Get Started

Core Concepts

Guides

Register a Domain with NameGrid: Step-by-Step Guide

Contact information requirements

​Contact information requirements

Contact information requirements