A session represents a single verification attempt. Every interaction with Verifa starts by creating a session — it tracks the user through capture, processing, and the final decision.
Environment isolation: Verifa keys are environment-scoped. A live key
(vk_live_*) cannot fetch sandbox sessions (or identities/workflows) and
vice versa — mismatched requests return 404. Use the matching key for the
environment you want to query.
Active: pending, capturing, processing, awaiting_external,
under_review, sandbox_pending
Terminal: completed, expired, failed
Once a session reaches a terminal status, its result is final and cannot change
(except through manual review of under_review sessions).
The capture_url contains a single-use token that expires after 20 minutes. The
qr_code_data_url is a base64-encoded PNG of the capture URL, useful for
displaying a QR code for mobile users.
If you already know some applicant data — from a signup form, an internal CRM,
or a prior session — pass it under fields to seed the verification record.
Values are stored encrypted at rest and become available to risk signals and
workflow conditions.
Pre-filling does not skip capture steps. The applicant still completes the capture flow; pre-filled values feed risk signals and workflow conditions, and will populate the form as it’s rendered.
To ease migration from other identity platforms, POST /api/v1/sessions
accepts alternative names for every parameter and inside fields. Like the
rest of the Verifa API, you can send keys in snake_case, kebab-case, or
camelCase — they’re all normalised internally. The endpoint also accepts a
JSON:API-style envelope ({"data": {"attributes": {...}}}) — the inner
attributes object is treated as the request body, and any sibling keys
outside attributes are ignored.
Responses always use the canonical shape regardless of which payload form you send.
Returns the full session object including status, metadata, tags, and linked review case information.
Re-issue a capture token for an expired or abandoned session:
Returns a new capture_url with a fresh token. The original documents and
progress are preserved.
Force-expire an active session:
Re-run the verification workflow on a completed session:
Useful after updating workflow rules — the original documents are re-evaluated against the current workflow configuration.
Retrieve signed URLs for the uploaded documents:
Document URLs are HMAC-signed and expire after 5 minutes (configurable). See Data Access for details.
Returns the fraud signal assessment including risk score, risk level, and triggered signals. See Fraud Signals for details.
The session result is a separate object containing the verification outcome.
Fetch it after the session reaches completed or under_review:
Export all decrypted PII and document URLs for a session in a single JSON document — used to satisfy GDPR Article 15 access requests:
Documents in the export include 24-hour TTL signed download URLs. The call is
audit-logged as api.session.export. See Data Access for
the equivalent identity-level export.
Delete all PII and document images for a session:
Redaction is permanent and irreversible. See Data Retention for automatic retention policies and GDPR compliance.
Sessions fire these webhook events: