Sessions

A session is a short-lived verification attempt. Your server creates it; the user completes it inside the iframe; the platform writes the result to a verification record and fires a webhook.

Creating a session

POST /v1/sessions
Authorization: Bearer ak_test_...
Idempotency-Key: 5b41362b-...
Content-Type: application/json
 
{
  "template_id": "tpl_abc123def456",
  "metadata": { "customer_id": "cus_123" },
  "redirect_url": "https://yourapp.example.com/kyc/complete"
}

Session shape is controlled by a verification template that your workspace owns and versions via the dashboard. At session create time we snapshot the template's flow_config onto the session — the iframe renders from that immutable snapshot, so edits to the template never change an in-flight session.

Pass template_id or template_slug to pin a specific template.
Omit both to use your workspace's default template. In test mode, if no default is set, the platform scaffold is used as a fallback so you can prototype without configuring a template first.
The response returns the resolved template_id and template_version.

Idempotency

Every mutating /v1/* request supports an Idempotency-Key header. The platform stores the request body hash in KV for 24 hours. Replaying the same key with the same body returns the original response; replaying with a different body returns idempotency_conflict.

Session lifecycle

created → requires_input → in_progress → (completed | failed | requires_review | canceled | expired)

created — session exists but iframe has not loaded.
requires_input — iframe loaded, waiting on user input.
in_progress — user is actively submitting.
completed — all checks passed, verification approved.
failed — at least one check failed decisively.
requires_review — manual review by your internal team.
canceled — user or tenant aborted.
expired — session TTL exceeded (default 30 minutes).

Fetching verifications

List:

GET /v1/verifications?status=requires_review&limit=50

Detail:

GET /v1/verifications/ver_...

The detail endpoint returns every check, the resolved fields extracted from the ID, and media URLs (R2 pre-signed, expire in 15 minutes).

Data processors

For GDPR / compliance purposes, the platform routes each check type to a specific upstream AI provider. Routing is configurable per tenant via the admin console; the defaults are:

Check	Primary provider	Fallback
`id_document`	Azure Document Intelligence	Gemini Vision
`address_document`	Azure Document Intelligence	Gemini Vision
`liveness`	Gemini Vision (passive)	—
`face_match`	AWS Rekognition (CompareFaces)	Gemini Vision

Notes:

Azure Face API is provisioned but the verify endpoint is gated by Microsoft's Limited Access approval. Until that's granted, face_match routes through AWS Rekognition.
Fallbacks fire only when the primary throws or returns an unprocessable result. They are not used for confidence boosting.
Tenant routing overrides are stored against the workspace and applied before the global default. Talk to support if you need EU-only routing or a specific provider exclusion.