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.
Last updated
On this page
- The price object
- The domain object
- The order object
- POST /v1/domains/check
- POST /v1/domains/quote
- POST /v1/domains
- POST /v1/domains/transfers
- GET /v1/domains
- GET /v1/domains/{domain}
- PATCH /v1/domains/{domain}
- POST /v1/domains/{domain}/renew
- POST /v1/domains/{domain}/transfer-code
- PUT /v1/domains/{domain}/nameservers
- DNS records
- Forwarding
- Orders
- 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.
{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). |
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
api.primaryapi.com/ v1/ domains/ checkAuth: 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). |
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 for years, or null) and renewUsdPerYear.
POST /v1/domains/quote
api.primaryapi.com/ v1/ domains/ quoteAuth: 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
api.primaryapi.com/ v1/ domainsAuth: 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). |
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
api.primaryapi.com/ v1/ domains/ transfersAuth: 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
api.primaryapi.com/ v1/ domainsAuth: 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}
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}
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
api.primaryapi.com/ v1/ domains/ {domain}/ renewAuth: 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
api.primaryapi.com/ v1/ domains/ {domain}/ transfer-codeAuth: 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
api.primaryapi.com/ v1/ domains/ {domain}/ nameserversAuth: 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
api.primaryapi.com/ v1/ domains/ {domain}/ dnsAuth: 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
api.primaryapi.com/ v1/ domains/ {domain}/ forwardingAuth: 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
api.primaryapi.com/ v1/ domains/ ordersAuth: 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
api.primaryapi.com/ v1/ domain-contactsAuth: Any API key or a dashboard session
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.