The full Name.ai Partner API. Every call is authenticated with HMAC headers and gated by the scopes granted to your credential. Endpoints below are live in sandbox; production switches on after approval. Some surfaces (brokerage, pay-with-name.ai, referral) unlock only when the matching scope is enabled for you.
1. Get sandbox credentials (key id + secret) after applying.
2. Sign every request — see Authentication for the canonical string + HMAC.
3. Start with GET /api/partner/v1/domains/search?q=ai, then a quote → order, or a checkout-session.
4. Subscribe a webhook so you don't have to poll for fulfilment / settlement / brokerage updates.
Find sellable inventory and look up a single domain. DSN-gated; search is query-required and capped (max 5 results) — no bulk export.
| Method | Path | Scope | Notes |
|---|---|---|---|
| GET | /api/partner/v1/domains/search?q= | search | Hybrid semantic + keyword search, reranked. Returns up to 5 genuinely-relevant domains (fewer if fewer match). |
| GET | /api/partner/v1/domains/{name} | search | Single-domain detail: price + availability. |
| GET | /api/partner/v1/availability?domain= | search | Fast yes/no + price (200 with available:false rather than 404). |
| GET | /api/partner/v1/pricing?domain= | search | Buy-now + floor price for one domain (404 if unlisted). |
You charge the buyer on your own app, then notify us. We deliver the domain and settle your share. Idempotency-Key required on orders.
| Method | Path | Scope | Notes |
|---|---|---|---|
| POST | /api/partner/v1/quotes | buy | Firm price + 10-min reservation (signed quote token). |
| POST | /api/partner/v1/orders | buy | Record a partner-collected sale (you already charged the buyer). Pass quote_id + external_payment_ref. |
| GET | /api/partner/v1/orders | search | List your orders (status filter + cursor pagination). |
| GET | /api/partner/v1/orders/{id} | search | Order + transfer/fulfilment status (timeline). |
The option every partner can offer (the only option for non-MoR partners). We collect payment; you earn a commission paid at settlement.
| Method | Path | Scope | Notes |
|---|---|---|---|
| POST | /api/partner/v1/checkout-session | embed | Returns a hosted "Pay with name.ai" link (our lander). Buyer pays + registers there; the sale is attributed to you. |
Your user opts into our brokerage service. We run the acquisition and you earn your cut at settlement.
| Method | Path | Scope | Notes |
|---|---|---|---|
| GET | /api/partner/v1/brokerage/eligibility?domain= | broker | Can we broker this domain? Ineligible if it runs an active/live site or is already in a case. |
| POST | /api/partner/v1/brokerage | broker | Create a case (tier managed|self_serve, buyer_email, budget). Returns a no-login progress link for the buyer. |
| GET | /api/partner/v1/brokerage/{id} | broker | Case status/details (yours only). Plus a brokerage.case_completed webhook on deal close. |
Reconcile what you owe us (partner-collected) and what we owe you (name.ai-collected / brokerage).
| Method | Path | Scope | Notes |
|---|---|---|---|
| GET | /api/partner/v1/settlements | buy | Per-period statement: gross sold, commission retained, amount owed to name.ai. |
| GET | /api/partner/v1/transactions | report | Full sales history (every domain sold through you) + totals (GMV, commission). Filters: from/to, status, payment_model. |
| POST | /api/partner/v1/refunds | buy | Request a refund/clawback for a partner-collected order. |
Refer buyers to name.ai and earn commission. Requires your credential to be linked to an affiliate account.
| Method | Path | Scope | Notes |
|---|---|---|---|
| POST | /api/partner/v1/links | refer | Create a tracking link (generic / domain / product). |
| GET | /api/partner/v1/links | refer | List your links with per-link click/sale stats. |
| GET | /api/partner/v1/me/clicks | report | Your referral clicks (windowed). |
| GET | /api/partner/v1/me/sales | report | Your referred sales + commission earned. |
| GET | /api/partner/v1/me/commissions | report | Commission line items + ledger-derived balance. |
| GET | /api/partner/v1/me/payouts | report | Your payout history + total paid. |
| GET | /api/partner/v1/analytics | report | Aggregated performance — orders GMV + referral funnel. |
Subscribe once; we deliver signed events and keep a replayable history.
| Method | Path | Scope | Notes |
|---|---|---|---|
| PUT | /api/partner/webhooks | webhook | Set your webhook endpoint + secret. Events are signed (X-NameAI-Signature). |
| GET | /api/partner/v1/events | webhook | Signed event history + replay cursor (order.* / transfer.* / brokerage.*). |