> ## Documentation Index
> Fetch the complete documentation index at: https://developer.verilock.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Video KYC

> Verify identities through self-recorded video or live agent video calls.

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

| Mode          | Description                                            | Use Case                     |
| ------------- | ------------------------------------------------------ | ---------------------------- |
| `self_record` | User records a short video following on-screen prompts | High-volume, async review    |
| `live_agent`  | User joins a real-time video call with a trained agent | High-risk, regulated markets |

## Creating a Session with Video KYC

Include a `video` step in the verification profile when creating a session:

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://verilock.io/api/v1/sessions",
      headers={
          "Authorization": "Bearer qi_live_your_api_key_here",
          "Content-Type": "application/json",
      },
      json={
          "profile": {
              "steps": ["document", "selfie", "video"],
              "video_mode": "self_record",
          },
          "redirect_url": "https://yourapp.com/callback",
          "external_id": "user_12345",
      },
  )
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://verilock.io/api/v1/sessions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer qi_live_your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      profile: {
        steps: ['document', 'selfie', 'video'],
        video_mode: 'self_record',
      },
      redirect_url: 'https://yourapp.com/callback',
      external_id: 'user_12345',
    }),
  });
  ```
</RequestExample>

### Video Mode Options

| Field                | Type    | Default       | Description                                                    |
| -------------------- | ------- | ------------- | -------------------------------------------------------------- |
| `video_mode`         | string  | `self_record` | `self_record` or `live_agent`                                  |
| `video_max_duration` | integer | `60`          | Maximum recording length in seconds (self-record only)         |
| `video_language`     | string  | `en`          | Prompt 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.

<ResponseExample>
  ```json 200 Self-Record Result theme={null}
  {
    "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"
  }
  ```

  ```json 200 Live Agent Result theme={null}
  {
    "session_id": "ses_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "video_mode": "live_agent",
    "status": "completed",
    "result": "approved",
    "video_url": "https://verilock.io/api/v1/sessions/ses_a1b2c3d4-.../video/download",
    "duration_seconds": 185,
    "face_match_score": 98.1,
    "liveness_score": 95.7,
    "agent_id": "agent_7890abcd",
    "agent_notes": "Identity confirmed. Document matches applicant.",
    "call_started_at": "2026-03-18T10:10:00Z",
    "call_ended_at": "2026-03-18T10:13:05Z"
  }
  ```
</ResponseExample>

## Response Fields

| Field              | Type    | Description                                                      |
| ------------------ | ------- | ---------------------------------------------------------------- |
| `session_id`       | string  | The parent session ID                                            |
| `video_mode`       | string  | `self_record` or `live_agent`                                    |
| `status`           | string  | `pending`, `in_progress`, `completed`, `expired`                 |
| `result`           | string  | `approved`, `declined`, `needs_review`                           |
| `video_url`        | string  | Signed URL to download the recorded video (expires after 1 hour) |
| `duration_seconds` | integer | Length of the video in seconds                                   |
| `face_match_score` | number  | Similarity score comparing video face to selfie/document (0-100) |
| `liveness_score`   | number  | Confidence that the video is from a live person (0-100)          |
| `transcript`       | string  | Extracted speech transcript (self-record only)                   |
| `agent_id`         | string  | ID of the reviewing agent (live agent only)                      |
| `agent_notes`      | string  | Notes left by the agent (live agent only)                        |

## Webhook Events

| Event             | Trigger                                                  |
| ----------------- | -------------------------------------------------------- |
| `video.completed` | Video recording or call finished and is ready for review |
| `video.reviewed`  | Video has been reviewed and a decision was made          |

```json video.completed theme={null}
{
  "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

<Steps>
  <Step title="Session created">
    Create a session with `video` in the steps array. The user is guided through document and selfie capture first.
  </Step>

  <Step title="Video recording">
    The user is shown on-screen prompts (e.g., "State your full name and today's date") and records a short video.
  </Step>

  <Step title="Processing">
    Verilock extracts the face from the video, runs liveness detection, and compares it to the selfie and document photo.
  </Step>

  <Step title="Review">
    The video and extracted data are available for manual review in the dashboard or via API.
  </Step>
</Steps>

## Live Agent Flow

<Steps>
  <Step title="Session created">
    Create a session with `video_mode: "live_agent"`. The user completes document and selfie steps first.
  </Step>

  <Step title="Agent queue">
    The user is placed in a queue. An available agent joins the video call.
  </Step>

  <Step title="Verification call">
    The agent verifies the user's identity by asking questions, requesting document display, and confirming liveness.
  </Step>

  <Step title="Decision">
    The agent approves or declines the session directly. Their notes are attached to the session.
  </Step>
</Steps>

<Note>
  Live agent mode requires the **Enterprise** plan. Agent availability is subject to your configured agent pool in **Dashboard > Video KYC > Agents**.
</Note>