Skip to main content
Video KYC adds a video verification step to your identity sessions, supporting both self-record mode (asynchronous) and live agent mode (real-time video call with a human reviewer).

​
Modes

ModeDescriptionUse Case
self_recordUser records a short video following on-screen promptsHigh-volume, async review
live_agentUser joins a real-time video call with a trained agentHigh-risk, regulated markets

​
Creating a Session with Video KYC

Include a video step in the verification profile when creating a session: 
curl -X POST \
  "https://verilock.io/api/v1/sessions" \
  -H "Authorization: Bearer qi_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "steps": ["document", "selfie", "video"],
      "video_mode": "self_record"
    },
    "redirect_url": "https://yourapp.com/callback",
    "external_id": "user_12345"
  }'

​
Video Mode Options

FieldTypeDefaultDescription
video_modestringself_recordself_record or live_agent
video_max_durationinteger60Maximum recording length in seconds (self-record only)
video_languagestringenPrompt language for self-record (en, es, fr, de, pt)

​
Retrieving Video Results

GET /v1/sessions/{id}/video
Returns the video verification details for a completed session. 
{
  "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "video_mode": "self_record",
  "status": "completed",
  "result": "approved",
  "video_url": "https://verilock.io/api/v1/sessions/ses_a1b2c3d4-.../video/download",
  "duration_seconds": 28,
  "face_match_score": 96.4,
  "liveness_score": 91.2,
  "transcript": "My name is Jean Dupont. Today is March 18, 2026.",
  "recorded_at": "2026-03-18T10:15:00Z",
  "reviewed_at": "2026-03-18T10:45:00Z"
}

​
Response Fields

FieldTypeDescription
session_idstringThe parent session ID
video_modestringself_record or live_agent
statusstringpending, in_progress, completed, expired
resultstringapproved, declined, needs_review
video_urlstringSigned URL to download the recorded video (expires after 1 hour)
duration_secondsintegerLength of the video in seconds
face_match_scorenumberSimilarity score comparing video face to selfie/document (0-100)
liveness_scorenumberConfidence that the video is from a live person (0-100)
transcriptstringExtracted speech transcript (self-record only)
agent_idstringID of the reviewing agent (live agent only)
agent_notesstringNotes left by the agent (live agent only)

​
Webhook Events

EventTrigger
video.completedVideo recording or call finished and is ready for review
video.reviewedVideo has been reviewed and a decision was made
video.completed
{
  "event": "video.completed",
  "data": {
    "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "video_mode": "self_record",
    "status": "completed",
    "duration_seconds": 28
  },
  "timestamp": "2026-03-18T10:15:01Z",
  "webhook_id": "wh_evt_abc123def456"
}

​
Self-Record Flow

1

Session created

Create a session with video in the steps array. The user is guided through document and selfie capture first.
2

Video recording

The user is shown on-screen prompts (e.g., “State your full name and today’s date”) and records a short video.
3

Processing

Verilock extracts the face from the video, runs liveness detection, and compares it to the selfie and document photo.
4

Review

The video and extracted data are available for manual review in the dashboard or via API.

​
Live Agent Flow

1

Session created

Create a session with video_mode: "live_agent". The user completes document and selfie steps first.
2

Agent queue

The user is placed in a queue. An available agent joins the video call.
3

Verification call

The agent verifies the user’s identity by asking questions, requesting document display, and confirming liveness.
4

Decision

The agent approves or declines the session directly. Their notes are attached to the session.
Live agent mode requires the Enterprise plan. Agent availability is subject to your configured agent pool in Dashboard > Video KYC > Agents.