Scope: broker

Brokerage

Let your users acquire domains that aren't listed on name.ai. You check eligibility, open a brokerage case, and name.ai negotiates acquisition on your buyer's behalf. You earn a commission on every completed deal — no payment handling required.

How brokerage works

1
Check eligibilityCall GET /brokerage/eligibility?domain=target.com — ineligible if the domain runs an active live site or already has an open case.
2
Open a caseCall POST /brokerage with the domain, tier (managed or self_serve), and buyer email. Returns a no-login progress link you can share with the buyer.
3
Name.ai negotiatesOur brokers outreach to the domain owner, negotiate price, and handle escrow and transfer logistics.
4
Receive webhook on closeWe fire brokerage.case_completed when a deal closes. Your commission is accrued and settled at the next cycle.
5
Poll if neededUse GET /brokerage/{id} to check case status at any time.

GET

/api/partner/v1/brokerage/eligibility

scope: broker

Check if a domain can be brokered before offering the service to your buyer. Returns eligible: true/false and a reason when ineligible.

Param	In	Required	Notes
domain	query	Yes	The domain you want to broker, e.g. targetdomain.com

Request

GET /api/partner/v1/brokerage/eligibility?domain=targetdomain.com
X-NameAI-Key-Id: pk_live_xxx
X-NameAI-Timestamp: <ts>
X-NameAI-Nonce: <uuid>
X-NameAI-Signature: v1=<hmac>

Response 200 — eligible

{
  "domain": "targetdomain.com",
  "eligible": true,
  "reason": null
}

Response 200 — ineligible

{
  "domain": "activebusiness.com",
  "eligible": false,
  "reason": "domain_has_active_site"
}

reason code	Meaning
domain_has_active_site	Domain resolves to a live, non-parked website — owner is using it.
case_already_open	An open brokerage case already exists for this domain.
domain_listed_on_nameai	Domain is already listed for sale on name.ai — use the standard buy flow instead.

POST

/api/partner/v1/brokerage

scope: broker

Open a brokerage case. Returns a signed progress link you can send directly to the buyer — no login required on their end.

Field	Required	Description
domain	Yes	Target domain to acquire.
tier	Yes	"managed" — our brokers handle everything; "self_serve" — buyer negotiates, we facilitate escrow.
buyer_email	Yes	Buyer's email. We send progress updates directly to them.
offer_price	No	Starting offer in USD (integer). If omitted, brokers determine an appropriate opening.

Request

POST /api/partner/v1/brokerage
Content-Type: application/json
X-NameAI-Key-Id: pk_live_xxx
X-NameAI-Timestamp: <ts>
X-NameAI-Nonce: <uuid>
X-NameAI-Signature: v1=<hmac>

{
  "domain": "targetdomain.com",
  "tier": "managed",
  "buyer_email": "buyer@example.com",
  "offer_price": 5000
}

Response 201

{
  "case_id": "bc_01JXYZ...",
  "domain": "targetdomain.com",
  "tier": "managed",
  "status": "OPEN",
  "progress_url": "https://name.ai/brokerage/bc_01JXYZ.../track?token=xxx",
  "created_at": "2026-06-08T10:00:00Z"
}

progress_url is a no-login link for the buyer. Share it in your confirmation email — they can track negotiation progress and communicate with the broker without creating a name.ai account.

GET

/api/partner/v1/brokerage/{case_id}

scope: broker

Fetch the current status and timeline of a brokerage case. Scoped to cases your credential created. We recommend using webhooks instead of polling for production integrations.

Request

GET /api/partner/v1/brokerage/bc_01JXYZ...
X-NameAI-Key-Id: pk_live_xxx
X-NameAI-Timestamp: <ts>
X-NameAI-Nonce: <uuid>
X-NameAI-Signature: v1=<hmac>

Response 200

{
  "case_id": "bc_01JXYZ...",
  "domain": "targetdomain.com",
  "tier": "managed",
  "status": "IN_NEGOTIATION",
  "buyer_email": "buyer@example.com",
  "offer_price": 5000,
  "agreed_price": null,
  "progress_url": "https://name.ai/brokerage/bc_01JXYZ.../track?token=xxx",
  "created_at": "2026-06-08T10:00:00Z",
  "updated_at": "2026-06-09T08:30:00Z"
}

Case status lifecycle

OPEN

Case created, name.ai is researching and outreaching to the domain owner.

IN_NEGOTIATION

Active negotiation with the seller underway.

DEAL_REACHED

Price agreed. Awaiting payment and transfer.

COMPLETED

Domain delivered to buyer. Commission accrued.

CLOSED_NO_DEAL

Could not reach a deal (seller unresponsive or price too high).

Webhook: brokerage.case_completed

Fired when a brokerage case is closed with a successful deal. Your commission is accrued at this point and will be settled at the next cycle. See Webhooks & events for the signing and delivery spec.

Event payload

{
  "event": "brokerage.case_completed",
  "case_id": "bc_01JXYZ...",
  "domain": "targetdomain.com",
  "agreed_price_cents": 650000,
  "currency": "USD",
  "partner_commission_cents": 32500,
  "buyer_email": "buyer@example.com",
  "completed_at": "2026-06-15T14:22:00Z"
}

Next: Referral & reporting → · Webhooks & events →