Client / Widget API

The surface the in-browser widget uses to drive a single session. Authenticated with the short-lived client token from POST /v1/sessions.

Base: /api/v1/client · Auth: X-Client-Token: <token> (or Authorization: Bearer <token>)

The token resolves the one session it was minted for; expired tokens are rejected.

WARNING

You normally don't call these endpoints directly; the widget does. They're documented for custom flows.

Endpoints

Method	Path	Description
GET	/v1/client/session	Fetch the session; marks it started on first load.
POST	/v1/client/document/front	Submit the document front; runs OCR + portrait extraction.
POST	/v1/client/document/back	Submit the document back (skipped for single-sided docs).
POST	/v1/client/liveness	Submit the selfie / passive liveness frame.
POST	/v1/client/address	Submit the claimed address (only when the workflow enables the address stage).
POST	/v1/client/complete	Finalize: run the decision engine and land the verdict.

Uploads

Document and liveness endpoints accept multipart/form-data with the image file. With mock providers you may include hint fields to script the outcome (e.g. confidence, expired, score, passed, similarityScore); see Provider drivers.

POST /api/v1/client/document/front
X-Client-Token: <token>
Content-Type: multipart/form-data

image=@front.jpg

Address

When the workflow enables the address stage, submit the claimed address fields (multipart/form-data). Depending on the configured methods, include a poa proof-of-address image and/or device latitude / longitude. With mock, the address_score / address_passed hints script the outcome.

POST /api/v1/client/address
X-Client-Token: <token>
Content-Type: multipart/form-data

line1=31 Gwarri Avenue
city=Kaduna
country=NG
latitude=10.48342
longitude=7.43488

Completing

POST /api/v1/client/complete
X-Client-Token: <token>

Enqueues the biometric + decision work (or runs inline with the sync queue). The session moves to processing, then to approved / requires_review / rejected. Read the result via the Public API or a webhook.

Limits

• Sessions expire (default 15 minutes); expired sessions reject further calls.
• Liveness is capped at 3 attempts per session.