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

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

> Check availability, submit contact details, and register a domain via the NameGrid API. Covers privacy, auto-renew, credits, and error handling.

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.

<Steps>
  <Step title="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.

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

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

  <Step title="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`.

    ```bash theme={null}
    curl https://api.namegrid.org/v1/account \
      -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx"
    ```

    <Tip>
      If your balance is too low, top it up at [https://app.namegrid.org](https://app.namegrid.org) before continuing. Each credit is worth **\$1 USD**.
    </Tip>
  </Step>

  <Step title="Register the domain">
    Submit a `POST` request to `/v1/domains` with your desired domain name, registration options, and full contact information.

    ```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": "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**

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

    <Warning>
      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.
    </Warning>

    <Note>
      Registrations are **non-refundable** once the order is placed. Double-check the domain name and registration period before submitting.
    </Note>
  </Step>

  <Step title="Verify registration">
    Confirm that your domain is live by fetching its details with `GET /v1/domains/yourdomain.com`.

    ```bash theme={null}
    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`.
  </Step>
</Steps>

## 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](https://en.wikipedia.org/wiki/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.