Device API

The calls the SDK and the hosted page make during a capture. You don't call these yourself when you use an SDK — they are here so you know what crosses the network, or if you build a client of your own.

auth Authorization: Bearer <sessionToken> prefix /api/sdk

Endpoints

Call	Request	Response
`POST /api/sdk/document/challenge`	Empty body	`{ "nonce", "expiresInSeconds" }`
`POST /api/sdk/document`	`multipart/form-data`: `image`, `nonce`, optional `documentType`, `side`	Step outcome
`POST /api/sdk/liveness/challenge`	Empty body	`{ "nonce", "expiresInSeconds", "actions" }`
`POST /api/sdk/liveness`	`multipart/form-data`: `frames` (up to 12), `nonce`	Step outcome
`POST /api/sdk/finalize`	Empty body	`{ "result", "detail" }` — a non-authoritative copy
`GET /api/sdk/status`	—	`{ "status", "currentStep", "stepsCompleted", "resultStatus" }`

Sequence

one FULL_CAPTURE sessionflow

GET  /api/sdk/status                 which steps remain
POST /api/sdk/document/challenge     → nonce
POST /api/sdk/document               image + nonce  (front, then back for two-sided cards)
POST /api/sdk/liveness/challenge     → nonce + actions, e.g. ["BLINK"]
POST /api/sdk/liveness               frames performing the actions + nonce
POST /api/sdk/finalize               → { result, detail }

Single-use challenges

Every submission must echo the nonce from its challenge. A nonce works once and expires after expiresInSeconds; a replayed or late one is rejected with BLINK_CHALLENGE_INVALID. The document step must complete before liveness starts (BLINK_STEP_OUT_OF_SEQUENCE).

Step outcome

200 OKjson

{ "ok": false, "step": "DOCUMENT", "code": "DOCUMENT_UNREADABLE", "detail": "…" }

A business failure is HTTP 200 with ok: false — check ok, not the status code. Images are JPEG, PNG or WebP.