NameVerdict API

How prepaid access works

1. Buy a bundle. We email you a key (nv_live_…).
2. Hand the key to your agent. Each call burns one credit per name.
3. Lost the key? Reply to the receipt email — we'll reissue.

Machine-payment flow

1. POST one to five names, the product brief, optional Nice class, and a globally unique Idempotency-Key.
2. Handle the returned MPP HTTP 402 challenge with a compatible wallet and retry using its one-time payment credential.
3. On HTTP 202 (or HTTP 200 for an exact paid retry), retain the returned statusUrl and private statusToken. An exact retry returns the original job without another charge.
4. Poll about every five seconds until the job is done, failed, or refunded.

# Initial request: a compatible MPP client handles the 402 and paid retry.
curl -X POST https://nameverdict.com/api/mpp/clearance \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c0e6674-7425-40de-944b-e07fc1f90ae7" \
  -d '{"names":["orielpath"],"niceClass":9,"productDescription":"Supply-chain forecasting software"}'

Quick start

# Submit one or more names (max 5 per request, ≤ uses_remaining)
# Optional Idempotency-Key (8-128 chars A-Za-z0-9_-): retrying with the
# same key returns the original job instead of spending credits again.
curl -X POST https://nameverdict.com/api/clearance \
  -H "Authorization: Bearer nv_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-run-2026-08-20-a" \
  -d '{"names":["acme","rocket"],"niceClass":9,"productDescription":"open-source CLI tool"}'

# Response
# { "ok": true, "jobId": "abc123", "statusUrl": "https://nameverdict.com/api/clearance/abc123",
#   "creditsRemaining": 3, "namesQueued": 2 }

# Poll until done
curl https://nameverdict.com/api/clearance/abc123 \
  -H "Authorization: Bearer nv_live_..."

# {"status":"running", ...}  → poll again in ~5s
# {"status":"done", "report": {...}, "reportUrl": "...", "creditsRemaining": 3}
# {"status":"failed", "error":"internal_error", "creditsRefunded": 2}