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"
}

Template-driven sessions

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).