{"openapi":"3.1.0","servers":[{"url":"https://nameverdict.com","description":"Production"}],"info":{"title":"NameVerdict Machine Payments API","version":"1.0.1","description":"Paid preliminary brand-name risk screening. Not trademark clearance or legal advice."},"externalDocs":{"description":"NameVerdict API integration, pricing, scope, and limitations","url":"https://nameverdict.com/api-access"},"x-service-info":{"categories":["brand-name screening","trademark risk","domains"],"docs":{"homepage":"https://nameverdict.com/api-access","llms":"https://nameverdict.com/llms.txt"}},"paths":{"/api/mpp/clearance":{"post":{"operationId":"purchaseNameVerdictScreening","summary":"Purchase a preliminary NameVerdict screening for one to five candidate names","description":"The initial request returns an MPP HTTP 402 challenge. Retry with a compatible one-time payment credential. This purchases the same automated six-signal preliminary screening as the browser and prepaid API products; it is not trademark clearance or legal advice.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"},"description":"A globally unique, UUID-grade key for this purchase attempt. Use a new key after a terminal refund."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["names"],"properties":{"names":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","minLength":1,"maxLength":64}},"niceClass":{"type":"integer","minimum":1,"maximum":45},"productDescription":{"type":"string","maxLength":2000}}},"examples":{"oneCandidate":{"value":{"names":["orielpath"],"niceClass":9,"productDescription":"Supply-chain forecasting software"}}}}}},"x-payment-info":{"offers":[{"method":"stripe","intent":"charge","amount":"3900","currency":"usd","description":"One NameVerdict candidate evaluation"},{"method":"stripe","intent":"charge","amount":"9900","currency":"usd","description":"Two through five NameVerdict candidate evaluations in one request"}]},"responses":{"200":{"description":"Exact paid retry: the same Idempotency-Key, normalized payload, and payment credential return the original job and token without another charge.","headers":{"Payment-Receipt":{"description":"Serialized MPP receipt for the successful Stripe payment.","schema":{"type":"string"}},"Cache-Control":{"description":"Private response caching policy.","schema":{"const":"private"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok","jobId","statusUrl","statusToken","namesQueued","payment","idempotentReplay"],"properties":{"ok":{"const":true},"jobId":{"type":"string","pattern":"^[0-9A-Za-z]{10}$"},"statusUrl":{"type":"string","format":"uri"},"statusToken":{"type":"string","description":"Bearer token used only to poll this job."},"namesQueued":{"type":"integer","minimum":1,"maximum":5},"payment":{"type":"object","required":["amountCents","currency","status"],"properties":{"amountCents":{"type":"integer"},"currency":{"const":"usd"},"status":{"const":"paid"}}},"idempotentReplay":{"const":true}}}}}},"202":{"description":"Payment accepted and screening job queued","headers":{"Payment-Receipt":{"description":"Serialized MPP receipt for the successful Stripe payment.","schema":{"type":"string"}},"Cache-Control":{"description":"Private response caching policy.","schema":{"const":"private"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok","jobId","statusUrl","statusToken","namesQueued","payment"],"properties":{"ok":{"const":true},"jobId":{"type":"string","pattern":"^[0-9A-Za-z]{10}$"},"statusUrl":{"type":"string","format":"uri"},"statusToken":{"type":"string","description":"Bearer token used only to poll this job."},"namesQueued":{"type":"integer","minimum":1,"maximum":5},"payment":{"type":"object","required":["amountCents","currency","status"],"properties":{"amountCents":{"type":"integer"},"currency":{"const":"usd"},"status":{"const":"paid"}}}}}}}},"400":{"description":"Invalid request"},"402":{"description":"MPP payment challenge. A compatible wallet reads WWW-Authenticate and retries with its one-time credential.","headers":{"WWW-Authenticate":{"description":"Serialized Machine Payments Protocol challenge.","schema":{"type":"string"}},"Cache-Control":{"schema":{"const":"no-store"}}}},"409":{"description":"Idempotency conflict or terminal payment state"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Service temporarily unavailable or payment reconciliation required"}}}},"/api/clearance/{jobId}":{"get":{"operationId":"getNameVerdictScreening","summary":"Poll a NameVerdict screening purchased through MPP","description":"Use the one-job bearer token returned by POST /api/mpp/clearance.","security":[{"jobToken":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9A-Za-z]{10}$"}}],"responses":{"200":{"description":"Current job state: running, done, failed, or refunded","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"enum":["running","done","failed","refunded"]},"report":{"type":"object"},"reportUrl":{"type":"string","format":"uri"},"namesCompleted":{"type":"integer"},"namesTotal":{"type":"integer"},"error":{"type":"string"},"payment":{"type":"object"}}}}}},"401":{"description":"Missing or invalid one-job bearer token"},"402":{"description":"Credential revoked or inactive"},"404":{"description":"Job not found"},"429":{"description":"Rate limit exceeded"}}}}},"components":{"securitySchemes":{"jobToken":{"type":"http","scheme":"bearer","bearerFormat":"nv_job_..."}}}}