> ## Documentation Index
> Fetch the complete documentation index at: https://docs.namegrid.org/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/domains — Submit a New Domain Registration

> POST /v1/domains — Register a domain against your workspace. Provide contact details, registration years, auto-renew, and privacy settings.

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

<ParamField body="domain" type="string" required>
  The fully-qualified domain name you want to register (e.g. `example.com`).
</ParamField>

<ParamField body="years" type="integer">
  The number of years to register the domain for. Must be between `1` and `10`. Defaults to `1` if omitted.
</ParamField>

<ParamField body="autoRenew" type="boolean">
  Set to `true` to automatically renew this domain before it expires. Defaults to `false` if omitted.
</ParamField>

<ParamField body="privacyEnabled" type="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.
</ParamField>

<ParamField body="contact" type="object" required>
  Registrant contact information required by the registry. All sub-fields below are strings.

  <Expandable title="contact fields">
    <ParamField body="contact.firstName" type="string" required>
      Registrant's first name.
    </ParamField>

    <ParamField body="contact.lastName" type="string" required>
      Registrant's last name.
    </ParamField>

    <ParamField body="contact.organization" type="string">
      Organization or company name. Optional for individual registrants.
    </ParamField>

    <ParamField body="contact.email" type="string" required>
      Registrant's email address. Used for registry notifications.
    </ParamField>

    <ParamField body="contact.phone" type="string" required>
      Registrant's phone number in E.164 format (e.g. `+1.5555550100`).
    </ParamField>

    <ParamField body="contact.address1" type="string" required>
      Primary street address line.
    </ParamField>

    <ParamField body="contact.address2" type="string">
      Secondary address line (suite, unit, floor, etc.). Optional.
    </ParamField>

    <ParamField body="contact.city" type="string" required>
      City or locality.
    </ParamField>

    <ParamField body="contact.stateProvince" type="string" required>
      State, province, or region.
    </ParamField>

    <ParamField body="contact.postalCode" type="string" required>
      Postal or ZIP code.
    </ParamField>

    <ParamField body="contact.country" type="string" required>
      Two-letter country code in ISO 3166-1 alpha-2 format (e.g. `US`, `GB`, `DE`).
    </ParamField>
  </Expandable>
</ParamField>

### Request Example

```bash theme={null}
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

<ResponseField name="domain" type="object">
  The newly registered domain object.

  <Expandable title="domain fields">
    <ResponseField name="name" type="string">
      The registered domain name.
    </ResponseField>

    <ResponseField name="status" type="string">
      Initial status of the domain, typically `active` once provisioning completes.
    </ResponseField>

    <ResponseField name="autoRenew" type="boolean">
      Whether automatic renewal is enabled.
    </ResponseField>

    <ResponseField name="privacyEnabled" type="boolean">
      Whether WHOIS privacy protection is enabled.
    </ResponseField>

    <ResponseField name="years" type="integer">
      The number of years the domain was registered for.
    </ResponseField>

    <ResponseField name="expiresAt" type="string">
      ISO 8601 timestamp for the domain's expiry date.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp for when the registration was created.
    </ResponseField>

    <ResponseField name="creditsCharged" type="integer">
      The number of credits deducted from your balance for this registration.
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "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
  }
}
```

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

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