Loading…
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.
| 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. |
| 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. |
| 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). |
| 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. |
| 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. |
| Path | Scope | Description |
|---|---|---|
| /refunds | buy | Request a refund/clawback for a partner-collected order (pre-TRANSFER_COMPLETED only). |
| 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. |
| Path | Scope | Description |
|---|---|---|
| /brokerage | broker | Open a brokerage acquisition case. Returns a no-login progress link for the buyer. |
| 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. |
| 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. |
| 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. |
Retry-After header (seconds to wait).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 →