Full API reference

All endpoints served at https://name.ai/api/partner/v1. Each request must carry the four authentication headers and the credential must hold the required scope.

API scopes

Scope	Grants access to
search	Search inventory, get prices, check availability.
embed	Create hosted checkout sessions (non-MoR lander redirect).
buy	Get quotes, record orders, request refunds, view settlements.
broker	Check brokerage eligibility, open cases, track acquisition progress.
refer	Create and list tracked referral links.
report	Read clicks, sales, commissions, payouts, analytics, transaction history.
webhook	Register delivery endpoint; read event history.

GET

Discovery

Path	Scope	Description
/domains/search	search	Semantic + keyword search over listed inventory. Query param q required.
/domains/{name}	search	Single-domain detail: price, availability, metadata.
/availability	search	Fast yes/no availability check. Returns available: false (not 404) for unlisted domains.
/pricing	search	Buy-now price for a specific domain. 404 if not listed.

POST

MoR — you collect payment

Path	Scope	Description
/quotes	buy	Lock the current buy-now price for 10 minutes. Returns a signed quote_id.
/orders	buy	Notify name.ai that you have collected payment. Idempotency-Key required.

GET

MoR — order status

Path	Scope	Description
/orders	buy	List your orders. Filter by status, domain, or date range.
/orders/{public_id}	buy	Single order detail. Poll to track transfer lifecycle (or use webhooks).

POST

Non-MoR — name.ai collects payment

Path	Scope	Description
/checkout-session	embed	Create a hosted lander URL with a signed ?pt= token. Redirect your buyer to checkout_url. Expires in 7 days.

GET

Settlement & reconciliation

Path	Scope	Description
/settlements	buy	Per-period settlement statements showing what you owe or are owed.
/transactions	report	Full sales history with GMV and commission totals.
/payouts	report	Payouts name.ai has made to you (non-MoR commissions, brokerage).
/brokerage	report	List brokerage acquisition cases and their outcomes.

POST

Refunds

Path	Scope	Description
/refunds	buy	Request a refund/clawback for a partner-collected order (pre-TRANSFER_COMPLETED only).

GET

Brokerage — acquire unlisted domains

Path	Scope	Description
/brokerage/eligibility	broker	Check if a domain is eligible for brokerage (not an active site, no open case).
/brokerage/{case_id}	broker	Fetch status and timeline of a brokerage case.

POST

Brokerage — create case

Path	Scope	Description
/brokerage	broker	Open a brokerage acquisition case. Returns a no-login progress link for the buyer.

Referral — tracking links

Method	Path	Scope	Description
POST	/links	refer	Create a tracked referral link (generic or domain-specific). Embed in your site or email.
GET	/links	refer	List all your referral links with per-link click and conversion stats.

GET

Reporting — your performance

Path	Scope	Description
/me/clicks	report	Referral click totals for your account, optionally windowed by date.
/me/sales	report	All sales attributed to your referral links — buyer, domain, amount, commission.
/me/commissions	report	Commission ledger: accrued, pending, paid out, and reversed — with running balance.
/me/payouts	report	All payouts name.ai has sent to your account with dates and totals.
/analytics	report	Aggregated referral funnel + GMV + commission over a date range.

Webhooks & events

Method	Path	Scope	Description
PUT	/webhooks	webhook	Register or update your delivery URL and signing secret.
GET	/events	webhook	Replayable event history. Use after_id cursor to catch up after downtime.

Request headers (all endpoints)

Header	Value
X-NameAI-Key-Id	Your credential public key (pk_live_… or pk_test_…)
X-NameAI-Timestamp	Unix seconds (UTC). Must be within ±5 minutes of server time.
X-NameAI-Nonce	Per-request UUID v4. Prevents replay attacks.
X-NameAI-Signature	v1=<HMAC-SHA256 hex>. See Authentication for signing spec.
Idempotency-Key	Required for POST /orders only. UUID v4, unique per operation.

Error codes

HTTP	code	Meaning
400	validation_error	Missing or malformed field. Check message for details.
401	invalid_signature	HMAC signature rejected. Check key, timestamp, nonce, body.
401	missing_credentials	No X-NameAI-Key-Id header present.
403	forbidden	Credential does not have the required scope.
404	not_found	Domain not listed, or order ID not found.
409	conflict	Idempotency-Key re-used with different body.
422	price_mismatch	sale_price_cents does not match current listing price.
422	quote_expired	quote_id has expired (10-minute window).
429	rate_limited	Rate limit exceeded. Honour Retry-After header.
500	internal_error	Unexpected server error. Retry with exponential back-off.

Rate limits

Search endpoints: 60 req/min per credential.
Write endpoints (quotes, orders, checkout-session): 20 req/min per credential.
Reporting endpoints (settlements, transactions, payouts): 30 req/min per credential.
When limited, the response includes a Retry-After header (seconds to wait).

Sandbox vs live: Credentials issued with environment SANDBOX use a separate inventory of test domains with synthetic pricing. Switch to LIVE credentials to access real domains. Both environments use the same base URL — the credential determines which inventory is served. See Quick start for details.

Need more detail? Each endpoint links to a dedicated guide above. Start with Quick start →