---
title: "Liveness Detection v2"
method: POST
path: "/v2/verify/liveness"
tags: ["Liveness v2"]
---

# Liveness Detection v2

`POST /v2/verify/liveness`

Runs a passive liveness check on a supplied face image to determine whether it represents a live person rather than a spoof (printed photo, screen replay, or mask). Returns a boolean `is_live` verdict together with a normalized liveness score. A low-confidence or spoofed image still completes successfully (`status: "success"`) with `is_live: false`.

**Response contract:** Every completed verification returns HTTP 200. A successful result returns `status: "success"` with `error_code: null` and a populated `data` object. A valid request with no matching record (or a business rejection) also returns HTTP 200 with `status: "failed"`, a non-null `error_code`, and `data: null`. Do not treat HTTP 200 alone as success — always branch on `status` and inspect `error_code`. Authenticate with your `X-Client-ID` and `X-API-KEY` headers. Transport, auth, and validation problems use standard 4xx/5xx status codes.

## Request body

- LivenessV2Request
  - `person` string, required — Face image to evaluate, as a base64-encoded string (raw base64 or a data URI).

## Response `200`

Liveness check completed. `data.is_live` carries the verdict.

- LivenessResponse
  - `status` string, required
  - `message` string, nullable
  - `error_code` string, nullable
  - `data` LivenessData
    - `is_live` boolean, nullable
    - `liveness_score` unknown
    - `extras` object, nullable
  - `tranx_id` string, nullable
  - `timestamp` string, nullable

## Other responses

- `400` — Invalid input — malformed request or missing required fields.
- `401` — Missing or invalid authentication credentials (X-Client-ID / X-API-KEY).
- `422` — Request body failed schema validation.
- `429` — Too many requests — rate limited (IDTO_006). Retry after a short wait.
- `500` — Internal server error.
- `503` — Vendor temporarily unavailable — verification could not be completed (IDTO_008). Retry shortly.

---

[API](https://skmtc.dev/idto/apis/verification-api.md) · [All operations](https://skmtc.dev/idto/apis/verification-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/idto/verification-api/revisions/e3d57dab8db4/schema)