# Domains

Reference for /v1/domains and /v1/domain-contacts. Check availability and prices, register, renew and transfer domains, change their settings, nameservers, DNS records and forwarding, and manage registrant contacts.

Every endpoint here works on the caller's workspace only: a domain, order or contact of another workspace answers `404 not_found`. Reads take any key (`full`, `run` or `view`) or a dashboard session. Purchases and settings take a `full` or `run` key or an owner, admin or billing member; DNS, nameservers and forwarding take a `full` or `run` key or an owner, admin or developer. Agent trial keys and OAuth tokens can read and check prices only. Guide: [Domains](/docs/domains).

`{domain}` in a path is the name in lower case, like `acme-labs.com` (internationalised names as punycode, `xn--…`). A suspended domain can be read; every change to it answers `403 domain_suspended`. A change the domain's state blocks (another order in progress, a pending registration) answers `409 domain_conflict` with `details.reason`.

## The price object

What an order costs **your** workspace, returned by checks, quotes and each domain's `renewal`.

| Field | Type | Description |
|---|---|---|
| `usd` | number | Total in US dollars for every year of the order. |
| `years` | integer | Years the price is for. |
| `credits` | integer | Credits it takes from the balance now: included credits first, then bought credits. |
| `includedCredits` | integer | The part paid by credits included with your plan. |
| `boughtCredits` | integer | The part paid by credits you bought. |
| `affordable` | boolean | Whether your balance covers it now. Free credits never count. |

## The domain object

| Field | Type | Description |
|---|---|---|
| `domain` | string | The name. |
| `status` | string | `pending` (registration or transfer under way), `active`, `expired` (still renewable), `suspended`, `transferred_out` or `lost`. |
| `registrar` | object | The sponsoring registrar: `id`, `name`, `url`, `registrationAgreementUrl`. |
| `createdAt` | string | When it was added to the workspace. |
| `registeredAt` | string or null | Registration date at the registrar (`null` while pending). |
| `expiresAt` | string or null | Expiry date. |
| `autoRenew` | boolean | PrimaryAPI renews it from your credits before it expires. |
| `privacy` | boolean | WHOIS privacy. |
| `locked` | boolean | Transfer lock: no other registrar can take it while `true`. |
| `nameservers` | string[] | Its nameservers. |
| `managedDns` | boolean | `true` on the registrar's DNS, where records and forwarding are managed with this API. |
| `contactId` | string or null | The registrant contact. |
| `verification` | object | `status` (`verified`, `pending`, `not_required`, `unknown`) and `deadline` of the registrant's email verification. |
| `renewal` | object or null | One year's renewal at today's price ([price object](#the-price-object)). |
| `nextAutoRenewAt` | string or null | The next automatic renewal attempt. |
| `autoRenewProblem` | string or null | Why the last automatic renewal didn't happen, until one succeeds. |
| `suspendedReason` | string or null | Why PrimaryAPI suspended it. |

## The order object

| Field | Type | Description |
|---|---|---|
| `id` | string | The order. |
| `domain` | string | The name. |
| `action` | string | `register`, `renew`, `transfer_in` or `auto_renew`. |
| `years` | integer | Years ordered. |
| `status` | string | `pending`, `processing`, `completed`, `failed` (not charged) or `checking` (the registrar's answer was lost; credits stay held until its records settle it). |
| `usd`, `credits` | number, integer | What it cost. |
| `createdAt`, `completedAt` | string, string or null | When it was placed and finished. |
| `error` | string or null | Why it failed. |

Purchases answer `{ "order": <order>, "domain": <domain or null> }`: **201 Created** when the order completed, **202 Accepted** while it is still open.

## POST /v1/domains/check

`POST https://api.primaryapi.com/v1/domains/check`

Auth: Any API key, OAuth token or dashboard session

Availability and your price for up to 20 names. Free.

| Field | Type | Required | Description |
|---|---|---|---|
| `domains` | string[] | yes | 1 to 20 names. |
| `years` | integer | no | Years to price a registration for, 1–10 (default 1). |

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/domains/check" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains":["acme-labs.com","acme-labs.dev"]}'
```

**200 OK**: `{ "results": [ … ] }`, one per name: `domain`, `available`, `premium`, `reason` (why not, when unavailable), `register` (a [price](#the-price-object) for `years`, or `null`) and `renewUsdPerYear`.

## POST /v1/domains/quote

`POST https://api.primaryapi.com/v1/domains/quote`

Auth: Any API key, OAuth token or dashboard session

The price of one order. Free.

| Field | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes | The name. |
| `action` | string | yes | `register`, `renew` or `transfer_in`. |
| `years` | integer | no | 1–10 (default 1). |

**200 OK**: `{ "domain", "action", "premium", "price": <price> }`.

## POST /v1/domains

`POST https://api.primaryapi.com/v1/domains`

Auth: API key with run or full access, or a dashboard session (owners, admins, billing members)

Registers a domain and pays for it in credits. Send an `Idempotency-Key` header: the same key with the same body returns the same order.

| Field | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes | The name. |
| `years` | integer | no | 1–10 (default 1). |
| `contactId` | string | no | The registrant. Default: the workspace's default contact (one must exist). |
| `autoRenew` | boolean | no | Default `true`. |
| `privacy` | boolean | no | WHOIS privacy, default `true`. |
| `nameservers` | string[] | no | 2–13 custom nameservers. Default: the registrar's DNS. |
| `maxUsd` | number | no | Refuse the order if it would cost more. Required for premium names. |
| `acceptRegistrationAgreement` | `true` | yes | You accept the registrar's Registration Agreement ([Domain registration terms](/domain-registration)). |

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/domains" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: register-acme-labs-1" \
  -d '{"domain":"acme-labs.dev","years":1,"maxUsd":25,"acceptRegistrationAgreement":true}'
```

Errors: `403 domains_not_allowed` (`details.missing`: `email_verified`, `bought_credits`), `402 insufficient_balance`, `402 key_limit_reached`, `409 domain_unavailable` (`details.reason`), `409 domain_price_limit` (over `maxUsd`, or a premium name without it; `details.priceUsd`), `409 idempotency_conflict`, `429 rate_limited` (more than 10 new domains in a UTC day). None is charged.

## POST /v1/domains/transfers

`POST https://api.primaryapi.com/v1/domains/transfers`

Auth: API key with run or full access, or a dashboard session (owners, admins, billing members)

Transfers a domain in from another registrar. Same rules and errors as registering; the order stays `processing` until the registrar finishes it, usually in a few days.

| Field | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes | The name. |
| `authCode` | string | yes | The transfer code from the current registrar. |
| `contactId`, `autoRenew`, `privacy`, `maxUsd` | | no | As for registering. |
| `acceptRegistrationAgreement` | `true` | yes | As for registering. |

## GET /v1/domains

`GET https://api.primaryapi.com/v1/domains`

Auth: Any API key or a dashboard session

The workspace's domains. Query: `q` (part of a name), `includePast` (`true` adds transferred-out and lost domains), `limit` (1–200, default 50), `cursor`. **200 OK**: `{ "domains": [<domain>, …], "nextCursor": "…" | null }`.

## GET /v1/domains/\{domain\}

`GET https://api.primaryapi.com/v1/domains/{domain}`

Auth: Any API key or a dashboard session

One domain. **200 OK**: the domain object.

## PATCH /v1/domains/\{domain\}

`PATCH https://api.primaryapi.com/v1/domains/{domain}`

Auth: API key with run or full access, or a dashboard session (owners, admins, billing members)

Changes `autoRenew`, `privacy`, `locked` or `contactId` (at least one). Free. **200 OK**: the domain.

## POST /v1/domains/\{domain\}/renew

`POST https://api.primaryapi.com/v1/domains/{domain}/renew`

Auth: API key with run or full access, or a dashboard session (owners, admins, billing members)

Renews now, for `years` (1–10, default 1), optionally capped by `maxUsd`. Send an `Idempotency-Key`. Same errors as registering.

## POST /v1/domains/\{domain\}/transfer-code

`POST https://api.primaryapi.com/v1/domains/{domain}/transfer-code`

Auth: API key with run or full access, or a dashboard session (owners, admins, billing members)

Asks the registrar to email the transfer code to the domain's registrant contact. The code is never returned. **200 OK**: `{ "sentTo": "…" }`.

## PUT /v1/domains/\{domain\}/nameservers

`PUT https://api.primaryapi.com/v1/domains/{domain}/nameservers`

Auth: API key with run or full access, or a dashboard session (owners, admins, developers)

Either `{ "nameservers": ["ns1.example.net", "ns2.example.net"] }` (2–13 hostnames) or `{ "useRegistrarDns": true }`. **200 OK**: the domain.

## DNS records

`GET https://api.primaryapi.com/v1/domains/{domain}/dns`

Auth: Any API key or a dashboard session

`GET /v1/domains/{domain}/dns` answers `{ "records": [ … ] }`; `POST` adds one, `PUT /v1/domains/{domain}/dns/{id}` replaces one, `DELETE /v1/domains/{domain}/dns/{id}` removes one (owners, admins, developers, or a `run` or `full` key). A record's `id` changes when it is edited: list again after a change.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | yes | `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV` or `CAA`. |
| `host` | string | yes | Relative to the domain: `@` for the domain itself, `www`, `_dmarc`… |
| `value` | string | yes | A: IPv4 · AAAA: IPv6 · CNAME/MX: a hostname · TXT: text · SRV: `weight port target` · CAA: `flag tag "value"`. |
| `ttl` | integer | no | 300–86,400 seconds (default 3,600). |
| `priority` | integer | no | MX preference or SRV priority. |

On a domain with custom nameservers, DNS and forwarding changes answer `409 domain_conflict`: switch it back to the registrar's DNS first.

## Forwarding

`GET https://api.primaryapi.com/v1/domains/{domain}/forwarding`

Auth: Any API key or a dashboard session

`GET` answers `{ "url": [ … ], "email": [ … ] }`. Add a web address forward with `POST …/forwarding/url` (`host`, default `@`; `url`; `type`: `permanent`, `temporary` or `masked`) and an email forward with `POST …/forwarding/email` (`localPart`, or `*` for every address; `to`: 1–5 addresses). Remove one with `DELETE …/forwarding/url/{id}` or `DELETE …/forwarding/email/{id}`. Each change answers the whole forwarding object.

## Orders

`GET https://api.primaryapi.com/v1/domains/orders`

Auth: Any API key or a dashboard session

`GET /v1/domains/orders` (query: `domain`, `limit`, `cursor`) answers `{ "orders": [<order>, …], "nextCursor": … }`; `GET /v1/domains/orders/{id}` answers one order.

## Registrant contacts

`GET https://api.primaryapi.com/v1/domain-contacts`

Auth: Any API key or a dashboard session

{/* TODO(verify): the list's wrapper key ("contacts") until the API controller lands; the dashboard also reads a bare array. */}

`GET /v1/domain-contacts` lists the workspace's contacts (`{ "contacts": [ … ] }`). `POST` adds one, `PUT /v1/domain-contacts/{id}` replaces one (and updates every domain that uses it at the registrar), `DELETE /v1/domain-contacts/{id}` removes one (not the default while others exist: `409 domain_conflict`), and `POST /v1/domain-contacts/{id}/default` makes one the default (owners, admins, billing members, or a `run` or `full` key).

| Field | Type | Required | Description |
|---|---|---|---|
| `firstName`, `lastName` | string | yes | Up to 64 characters each. |
| `organization` | string | no | Up to 128 characters. |
| `email` | string | yes | The registrar emails its verification link and transfer codes here. |
| `phone` | string | yes | International format, like `+15551234567`. |
| `address1`, `address2` | string | `address1` | Street address. |
| `city`, `state`, `postalCode` | string | `city`, `postalCode` | `state` where the country has them. |
| `country` | string | yes | Two-letter code, like `US`. |

A contact also has `id`, `isDefault`, `createdAt` and `updatedAt`.
