Hosted Verification

Create a hosted verification session that generates a URL for your end-users. They complete identity verification on a Dokai-hosted page (document upload, selfie, liveness check) and you receive the result via webhook or polling.

Requires: Starter plan or higher with kyc_verification feature enabled.

How it works

Create a session via POST /v1/verify/session. You receive a unique URL and session ID.

Redirect your end-user to the URL. They upload their identity document and take a selfie.

Dokai processes the verification (face match + liveness detection) automatically.

Receive the result via webhook (verification.completed / verification.failed) or poll the session status.

Create a session

POST/v1/verify/session

Send as application/json.

Parameter	Type	Required	Description
`webhook_url`	string	No	HTTPS URL to receive a POST callback when verification completes. Domain must be whitelisted in Dashboard > Webhooks.
`document_type`	string	No	Expected document type. Auto-detected if omitted.
`document_brand`	string	No	Expected regional variant. Auto-detected if omitted.

Examples

curl -X POST https://api.dokai.dev/v1/verify/session \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://hooks.example.com/dokai",
    "document_type": "identity_card"
  }'

Create session response

Returns 201 Created with the session details and hosted URL.

201 Created

{
  "id": "ver_abc123",
  "url": "https://app.dokai.dev/verify/eyJhbGci...",
  "status": "pending",
  "expires_at": "2026-03-12T10:30:00Z"
}

Field	Type	Description
`id`	string	Unique session identifier. Use this to poll for status.
`url`	string	The hosted verification URL. Redirect your end-user here.
`status`	string	Always `pending` on creation.
`expires_at`	string	ISO 8601 timestamp. Session expires after 24 hours.

Check session status

GET/v1/verify/session/:id

Poll this endpoint to check the status of a hosted verification session. Once the status is verified, unverified, or failed, the full result is available.

cURL

curl https://api.dokai.dev/v1/verify/session/ver_abc123 \
  -H "Authorization: Bearer dk_live_your_api_key"

200 OK — completed

{
  "id": "ver_abc123",
  "status": "verified",
  "type": "hosted",
  "face_match": {
    "matched": true,
    "score": 0.92,
    "threshold": 0.363
  },
  "liveness": {
    "passed": true,
    "score": 0.78,
    "checks": {
      "texture": 0.85,
      "frequency": 0.80,
      "reflection": 0.72,
      "sharpness": 0.92,
      "color": 0.75
    }
  },
  "identity": {
    "name": "AHMAD BIN IBRAHIM",
    "id_number": "901215-08-5523"
  },
  "created_at": "2026-03-11T10:30:00Z",
  "expires_at": "2026-03-12T10:30:00Z"
}

Session statuses

Status	Description
`pending`	Session created, waiting for user to start.
`document_uploaded`	User uploaded their document, selfie pending.
`processing`	Both images submitted, verification in progress.
`verified`	Identity verified. Face matched and liveness passed.
`unverified`	Verification completed but identity could not be confirmed (face mismatch or liveness failed).
`failed`	An error occurred during verification (e.g. no face detected).
`expired`	Session expired before completion (24-hour TTL).

Webhook events

If you provided a webhook_url when creating the session, Dokai will POST the result to your endpoint when verification completes.

Event	Description
`verification.completed`	Verification finished with status `verified` or `unverified`.
`verification.failed`	Verification encountered an error (no face detected, processing failure).

Webhook payloads are signed with X-Dokai-Signature. See the Webhooks guide for signature verification details.