IDV Session — Integration Overview
This guide explains the full lifecycle of an Identity Verification (IDV) Session in Ralio, from creation through the final KYC state change that unlocks account creation.What is an IDV Session?
An IDV (Identity Verification) Session is a single, time-limited verification attempt for a given user. When created, Ralio returns ahostedUrl — a ready-to-use verification page that you share with your end user. There is no redirect URL configuration; instead, your backend receives real-time updates via webhooks as the session progresses.
Each session has a 7-day expiry window. If the user does not complete verification within that period, the session expires and a new one must be created.
Prerequisites
Before creating an IDV Session you must have:- A registered user in the system (you will need their
uid) - A webhook endpoint configured in the Ralio Management Portal that subscribes to KYC events
Step 1 — Create an IDV Session
Call the endpoint below to initiate a new verification session for a user. Endpoint
Important: Store the id (session ID) in your system. You will use it to correlate the incoming webhook events with the correct user and session.
Step 2 — Share the Hosted URL with the User
ThehostedUrl returned in the response is the verification page for the end user. Direct the user to this URL through your product — for example, as a button in your onboarding flow or a link sent via email/SMS.
There is no configurable redirect URL. Once the user completes the verification flow on the hosted page, your system will be notified exclusively through webhook events.
Step 3 — Listen for Webhook Events
Configure your webhook endpoint to handle the following KYC events. Relevant events for IDV Sessions:| Event | Trigger |
|---|---|
kyc_session_verified | Session successfully verified |
kyc_session_manual_review | Session sent to manual compliance review |
kyc_session_failed | Session rejected |
kyc_session_expired | Session expired before completion |
kyc_state_updated | User’s KYC level changed (LIGHT → REGULAR) |
Session States Reference
An IDV Session moves through the following states during its lifecycle:| State | Code | Description |
|---|---|---|
NOT_STARTED | 1 | Session created, verification not yet begun |
STARTED | 2 | User has opened the hosted URL and is verifying |
VERIFIED | 3 | All checks passed — session approved |
REVIEW | 4 | Automatic checks inconclusive; sent to manual review |
REJECTED | 5 | Session failed — one or more checks refused |
EXPIRED | 6 | Session expired before the user completed verification |
Outcome Paths
Approved — kyc_session_verified
All verification checks passed. The session state transitions to VERIFIED.
What to do: Wait for the kyc_state_updated event (see KYC Level & Account Creation) before unlocking account creation for the user.
Manual Review — kyc_session_manual_review
Automatic checks could not conclusively verify the user. The session state transitions to REVIEW and is assigned to a compliance officer for manual inspection.
What to do: Inform the user that their verification is under review. No action is required on your side — the compliance team will process it. Once they reach a decision, you will receive either a kyc_session_verified or kyc_session_failed event.
Rejected — kyc_session_failed
One or more checks failed. The session state transitions to REJECTED. The webhook payload includes a checks array with structured failure reasons.
What to do: A rejected session is terminal — you cannot retry it. You must create a new IDV Session for the user to attempt verification again. Use the code and message fields to surface a meaningful error message to the user so they understand what went wrong.
Expired — kyc_session_expired
The session was not completed within the 7-day window. The session state transitions to EXPIRED.
What to do: Create a new IDV Session and share the new hostedUrl with the user.
KYC Level & Account Creation
Ralio maintains an overall KYC Level for each user, independently of individual sessions. The two levels are:| Level | Code | Description |
|---|---|---|
LIGHT | 2 | Basic verification — default initial state |
REGULAR | 1 | Full KYC completed |
LIGHT to REGULAR and fires a kyc_state_updated event:
Account creation is only permitted when the user’s KYC level isREGULAR. Do not attempt to create an account based on thekyc_session_verifiedevent alone — wait forkyc_state_updatedwithstate: "REGULAR".
Webhook Event Reference
| Event | Session State | Action Required |
|---|---|---|
kyc_session_verified | VERIFIED | Wait for kyc_state_updated → REGULAR |
kyc_session_manual_review | REVIEW | Notify user; await compliance decision |
kyc_session_failed | REJECTED | Read error codes; create a new IDV Session |
kyc_session_expired | EXPIRED | Create a new IDV Session |
kyc_state_updated | — | If state = REGULAR, unlock account creation |