Hosted flow overview

The hosted flow is the verification experience ThirdFactor renders for your applicant. You create a session on your server, redirect the user to the returned url, and ThirdFactor handles document capture, liveness, selfie, AML and every other enabled module — including the retake guidance that gets a usable image the first time. You never build capture UI.

Every verification runs through the same hosted flow, whichever way you start it:

When to use the hosted flow vs. the SDKs

Both delivery mechanisms drive the identical server-side engine, so the choice comes down to how completion is reported and whether you need NFC:

The applicant journey

End-to-end example

The three pieces below — create, redirect, webhook — are the whole integration. Field-by-field detail for the request lives in Create a session; the full webhook contract lives in Webhooks → Events.

curl -X POST "$TF_BASE_URL/v3/session/" \
  -H "x-api-key: $TF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kyc-user-42" \
  -d '{
    "workflow_id": "9c2f1c4e-9a2b-4f2f-8f0f-0f1f3f4f5f6f",
    "vendor_data": "user-42",
    "callback_url": "https://app.example.com/kyc/done",
    "contact_email": "[email protected]",
    "expires_in_hours": 24,
    "locale": "en"
  }'

{
  "id": "6f0e2b7a-1c2d-4e3f-9a1b-2c3d4e5f6a7b",
  "session_kind": "user",
  "status": "not_started",
  "url": "https://acme.example.com/verify/eyJhbGciOiJIUzI1NiJ9.abc123",
  "vendor_data": "user-42",
  "decision": "in_progress",
  "expires_at": "2026-07-13T08:00:00Z",
  "created_at": "2026-07-12T08:00:00Z"
}

{
  "session_id": "6f0e2b7a-1c2d-4e3f-9a1b-2c3d4e5f6a7b",
  "status": "approved",
  "decision": "approved",
  "decision_reason": "",
  "vendor_data": "user-42",
  "workflow_id": "9c2f1c4e-9a2b-4f2f-8f0f-0f1f3f4f5f6f",
  "application_id": null,
  "created_at": "2026-07-12T08:00:00Z",
  "completed_at": "2026-07-12T08:06:12Z",
  "event_type": "identity.kyc.session.approved",
  "idempotency_key": "b2a1c3d4-…"
}

Server-enforced modules

The applicant's client never chooses or weakens a step. The workflow — built in the console under Config → KYC Workflows — decides which modules run and how strict each one is, and the server enforces that:

• The configured liveness method (passive, colour-flash, or 3D-action) cannot be downgraded client-side.
• The applicant cannot skip a required module, reorder the flow, or mark their own result as passed. Applicant-facing results are deliberately shallow (pass/fail per step); scores, warnings and engine detail stay server-side and are only visible to operators in the console.
• Evidence (documents, selfies, liveness stills) is sensitive PII. It is only readable through the authenticated, tenant-ownership-checked console view — it is never served from the public media namespace.

Which workflow a session runs is resolved at create time — pin it explicitly with workflow_id. See Create a session and Concepts → Workflows.

Session lifecycle & expiry

A hosted URL is single-purpose and time-boxed. Its lifetime is set at create time (expires_in_hours, 1..720, default 48 for ThirdFactor Verify (/v3) sessions). Once it expires the applicant sees an expiry screen, the session settles as expired, and identity.kyc.session.expired fires.

Terminal sessions emit the standard signed webhook:

See Webhooks → Events and Concepts → Sessions for the full status/decision mapping.

Troubleshooting

The session URL 404s

This is almost always a mismatch between the URL you're opening and the one ThirdFactor returned:

• You rebuilt the URL instead of using the url field verbatim. The token is opaque; don't concatenate id onto a path yourself. Always redirect to the exact string returned by the create call.
• You mixed up link shapes. ThirdFactor Verify POST /v3/session/ returns /verify/<token>; the partner POST /api/v1/sessions/ and console-generated links return /s/<token>. Opening a /s/ token against /verify/ (or vice versa) 404s. See No-code links for which path each surface produces.
• The session was deleted. DELETE /v3/session/<id>/delete/ soft-deletes the session and its evidence; a URL for a deleted session is gone.
• The link was truncated in transit. Long tokens can get clipped by SMS templates, email link-shortening, or a wrapping line in a copy/paste. Log the full url your server received and diff it against what was actually sent.

The applicant is stuck on a step

Pull the session's server-side view first — it usually tells you exactly where it stalled:

curl -H "x-api-key: $TF_API_KEY" "$TF_BASE_URL/v3/session/<id>/logs/"
curl -H "x-api-key: $TF_API_KEY" "$TF_BASE_URL/v3/session/<id>/checklist/"

Common causes:

• NFC step opened outside a mobile SDK. If the workflow requires NFC chip reading, the applicant can't complete it in a plain browser hosted flow — NFC only runs inside the iOS, Android, and Flutter SDKs. Route these applicants through a mobile SDK, not the redirect link.
• OTP required but no contact info was supplied. If the workflow uses email or SMS OTP and you didn't pass contact_email / contact_phone on create, the applicant has to enter contact details themselves mid-flow — slower, and easy to abandon. Pass them at create time whenever you already have them.
• Terms & Conditions blocking silently. If T&C acceptance is required and the tenant hasn't set copy for the session's locale, the accept screen may render with fallback text an applicant doesn't trust enough to continue. Check Settings → Terms and Settings → Translations for that locale.

The callback never fires

"Callback" usually means one of two different things — make sure you're debugging the right one:

The webhook is the reliable channel. If it truly never arrives:

• Confirm an endpoint URL and signing secret are set under Console → Developers → Webhooks — an unconfigured endpoint has nothing to deliver to.
• Confirm your handler returns 2xx quickly. Delivery is at-least-once with backoff; a timeout, a 4xx/5xx, or a slow handler is treated as failed and retried, not dropped — but it also means "never fires" can actually mean "kept failing silently on your side."
• Check the delivery log on that same console screen — it lists every attempt with its response code and lets you replay one on demand.
• Confirm the session actually reached a terminal state. A session sitting in in_review hasn't fired a terminal event yet; that's expected, not broken.

FAQ

Related