Integration · API
Dull on purpose.
REST over HTTPS, JSON in and out, dated versions, idempotent writes and errors that tell you which field was wrong. There is nothing to learn here beyond the resources, which is the intention.
- RESTover HTTPS
- 24 hidempotency window
- 90 daysdeprecation notice
Contract
The parts you will rely on
- Versioning
- Dated, pinned per key
- Idempotency
Idempotency-Key, 24 hours- Errors
- Field-level, machine-readable
- Rate limits
- Per key, headers on every response
- Authentication
- Bearer key, server side only
- Clock
- UTC, RFC 3339
A key is pinned to a version. New versions do not reach you until you move, and a version is supported for at least 90 days after its successor is announced.
Replaying a create returns the original check. A retry storm during an incident cannot open five checks against one player.
A 422 names the field and the rule it broke. Nothing returns a bare 400 with prose in the body.
Remaining and reset are always present, so a client can slow down before it is told to stop.
Keys never reach a browser or a handset; the client gets short-lived step tokens instead.
Every timestamp in every payload and every evidence bundle, with no local-time variants.
Resources
The surface, in full
| Method and path | Does | Idempotent |
|---|---|---|
POST /v1/checks | Opens a check for one person in one market | Yes, 24 h |
GET /v1/checks/{id} | Current state, verdict and reasons | — |
POST /v1/checks/{id}/cancel | Abandons a check that is still collecting | Yes |
GET /v1/evidence/{id} | The sealed bundle behind a verdict | — |
GET /v1/events | The journal, for anything a webhook could not deliver | — |
POST /v1/policies | Publishes a policy version for a market | Yes |
POST /v1/exclusions | Publishes your exclusion file, where you are the authority | Yes |
Seven resources. A verification API that needs more than this is usually exposing its own internal structure rather than your problem.
Decisions
Why it is shaped this way
Why is the response not streamed?
Because the slow part is the player, not us. A check waits on a human finding their passport; holding a connection open for that is a cost to you and a fragility for both of us. The webhook exists for exactly this reason.
Why does the verdict not include a score?
It includes scores for the individual signals, in the evidence bundle. What it does not do is reduce them to a single number, because the single number is the thing that cannot be explained to a supervisor afterwards.
Can we pin a policy to a check retroactively?
No. A check records the policy version that decided it, and that record is immutable. Re-deciding under a new policy opens a new check that references the old one.