Scopes: refer · report

Referral & reporting

Generate tracked referral links, surface name.ai domains inside your own UI, and pull your performance data — clicks, conversions, commissions, and payouts — via API. Name.ai is Merchant of Record; you earn a commission on every sale that traces back to your link.

Who this is for: affiliates, comparison sites, and any partner that redirects buyers to name.ai rather than collecting payment themselves. If you collect payment on your own checkout, use the MoR order flow instead.

POST

/api/partner/v1/links

scope: refer

Create a tracked referral link. Any buyer who clicks the link and completes a purchase on name.ai earns you a commission. Links never expire.

Field	Required	Description
target_type	Yes	"generic" — links to the name.ai homepage; "domain" — deep-links directly to a specific domain listing.
domain	No	Required when target_type is "domain". The domain to link to, e.g. custodylawyer.com.
label	No	Internal label for your own reference (e.g. "June newsletter").

Request

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

{
  "target_type": "domain",
  "domain": "custodylawyer.com",
  "label": "June campaign"
}

Response 201

{
  "link_id": "lnk_01JXYZ...",
  "url": "https://name.ai/market/custodylawyer.com?ref=lnk_01JXYZ...",
  "target_type": "domain",
  "domain": "custodylawyer.com",
  "label": "June campaign",
  "clicks": 0,
  "conversions": 0,
  "created_at": "2026-06-08T10:00:00Z"
}

Embed the url in your site, email, or ad. The ?ref= parameter is how we attribute the click.

GET

/api/partner/v1/links

scope: refer

List all referral links your credential has created, with per-link click and conversion stats.

Param	Required	Notes
limit	No	Max results per page (default 20, max 100).
offset	No	Pagination offset.

Response 200

{
  "total": 3,
  "links": [
    {
      "link_id": "lnk_01JXYZ...",
      "url": "https://name.ai/market/custodylawyer.com?ref=lnk_01JXYZ...",
      "target_type": "domain",
      "domain": "custodylawyer.com",
      "label": "June campaign",
      "clicks": 142,
      "conversions": 4,
      "commission_earned_cents": 12000,
      "created_at": "2026-06-08T10:00:00Z"
    }
  ]
}

Reporting endpoints

All reporting endpoints require scope: report. They are read-only and scoped to your credential.

GET/api/partner/v1/me/clicks

Referral click totals for your account, optionally windowed by date.

Response 200

{
  "total_clicks": 1842,
  "unique_visitors": 1204,
  "period": { "from": "2026-05-01", "to": "2026-06-08" }
}

GET/api/partner/v1/me/sales

All sales attributed to your referral links — buyer, domain, amount, and commission earned.

Response 200

{
  "total": 12,
  "sales": [
    {
      "sale_id": "sale_01JABC...",
      "domain": "custodylawyer.com",
      "sale_price_cents": 250000,
      "currency": "USD",
      "commission_cents": 12500,
      "status": "accrued",
      "sold_at": "2026-06-05T14:00:00Z"
    }
  ]
}

GET/api/partner/v1/me/commissions

Commission ledger — every commission earned, grouped by status. Use this to see your balance and what's pending payout.

Response 200

{
  "summary": {
    "accrued_cents": 37500,
    "pending_cents": 12500,
    "paid_out_cents": 50000,
    "total_earned_cents": 100000
  },
  "commissions": [
    {
      "commission_id": "com_01JXYZ...",
      "domain": "custodylawyer.com",
      "amount_cents": 12500,
      "currency": "USD",
      "status": "accrued",
      "accrued_at": "2026-06-05T14:00:00Z",
      "paid_out_at": null
    }
  ]
}

Commission statuses:

accrued — sale confirmed, commission earned, awaiting settlement window.
pending — settlement cycle triggered, payout being processed.
paid_out — transferred to your account.
reversed — refund or chargeback; commission clawed back.

GET/api/partner/v1/me/payouts

All payouts name.ai has sent to your account with dates and totals.

Response 200

{
  "total_paid_cents": 50000,
  "payouts": [
    {
      "payout_id": "pay_01JXYZ...",
      "amount_cents": 50000,
      "currency": "USD",
      "status": "completed",
      "paid_at": "2026-06-01T09:00:00Z",
      "reference": "bank_transfer_xxx"
    }
  ]
}

GET

/api/partner/v1/analytics

scope: report

Aggregated performance metrics — referral funnel, GMV, and commission — across a date range.

Param	Required	Notes
from	No	ISO 8601 date, e.g. 2026-05-01. Defaults to 30 days ago.
to	No	ISO 8601 date, e.g. 2026-06-08. Defaults to today.

Request

GET /api/partner/v1/analytics?from=2026-05-01&to=2026-06-08
X-NameAI-Key-Id: pk_live_xxx
X-NameAI-Timestamp: <ts>
X-NameAI-Nonce: <uuid>
X-NameAI-Signature: v1=<hmac>

Response 200

{
  "period": { "from": "2026-05-01", "to": "2026-06-08" },
  "referral": {
    "clicks": 1842,
    "unique_visitors": 1204,
    "conversions": 12,
    "conversion_rate_pct": 0.65
  },
  "revenue": {
    "gmv_cents": 3000000,
    "commission_earned_cents": 150000,
    "currency": "USD"
  }
}

Next: Settlement → · Webhooks & events →