POST /v1/domains — Submit a New Domain Registration

Use this endpoint to register a new domain name against your workspace. You supply the domain, the desired registration length, optional settings like auto-renew and WHOIS privacy, and the registrant contact details required by the registry. On success, credits are debited from your balance and the domain is queued for provisioning.

Request

Method: POST
Path: /v1/domains

Header	Required	Value
`x-api-key`	Yes	Your API key
`Content-Type`	Yes	`application/json`

Body Parameters

string

required

The fully-qualified domain name you want to register (e.g. example.com).

integer

The number of years to register the domain for. Must be between 1 and 10. Defaults to 1 if omitted.

boolean

Set to true to automatically renew this domain before it expires. Defaults to false if omitted.

boolean

Set to true to enable WHOIS privacy protection, which replaces your contact details with proxy information in the public registry. Defaults to false if omitted.

object

required

Registrant contact information required by the registry. All sub-fields below are strings.

Show contact fields

string

required

Registrant’s first name.

string

required

Registrant’s last name.

string

Organization or company name. Optional for individual registrants.

string

required

Registrant’s email address. Used for registry notifications.

string

required

Registrant’s phone number in E.164 format (e.g. +1.5555550100).

string

required

Primary street address line.

string

Secondary address line (suite, unit, floor, etc.). Optional.

string

required

City or locality.

string

required

State, province, or region.

string

required

Postal or ZIP code.

string

required

Two-letter country code in ISO 3166-1 alpha-2 format (e.g. US, GB, DE).

Request Example

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": "Smith",
      "organization": "Acme Corp",
      "email": "jane@example.com",
      "phone": "+1.5555550100",
      "address1": "123 Main St",
      "address2": "Suite 4",
      "city": "Springfield",
      "stateProvince": "IL",
      "postalCode": "62701",
      "country": "US"
    }
  }'

Response — 200 OK

object

The newly registered domain object.

Show domain fields

string

The registered domain name.

string

Initial status of the domain, typically active once provisioning completes.

boolean

Whether automatic renewal is enabled.

boolean

Whether WHOIS privacy protection is enabled.

integer

The number of years the domain was registered for.

string

ISO 8601 timestamp for the domain’s expiry date.

string

ISO 8601 timestamp for when the registration was created.

integer

The number of credits deducted from your balance for this registration.

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

Credits are debited from your balance immediately when the registration succeeds. Domain registrations cannot be reversed once confirmed with the registry.

Errors

Status	Reason
`400`	`domain` or `contact` is missing, a required contact field is absent, or the TLD is not supported
`402`	Insufficient credits — response includes `required` (cost) and `balance` (current balance)
`409`	The domain is already registered or has a pending registration in progress

Overview

Domains

DNS Records

Account

POST /v1/domains — Submit a New Domain Registration

Request

Body Parameters

Request Example

Response — 200 OK

Errors

​Request

​Body Parameters

​Request Example

​Response — 200 OK

​Errors

Request

Body Parameters

Request Example

Response — 200 OK

Errors