Skip to content
Biometry

Check liveness

POST
/v2/liveness

Check face liveness, active speaker detection, and visual speech recognition anti-spoofing on the submitted video.

Authorizations

Request Body required

object
request
required
object
user_id
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9._:@-]+$/
display_name

Optional human-readable label for the user (e.g. an email), recorded on the transaction for display. Never used as an identity; user_id remains the biometric key.

string
<= 256 characters
session_id

Optional session identifier for combined scoring.

string format: uuid
nullable
trigger

Optional contextual trigger event name.

string
services
object
exclude

Services to skip from the verification pipeline.

Array<string>
Allowed values: face_liveness_detection active_speaker_detection visual_speech_recognition face_recognition voice_recognition
phrase
required

Expected spoken phrase; required by the v1 processing pipeline for all video verification calls.

string
vocabulary

Vocabulary hint for speech recognition (e.g. en_digits).

string
video
required

Captured video recording (with speech if checking active speaker / visual speech).

string format: binary

Responses

200

Liveness analysis complete.

object
data

Endpoint-specific payload; omitted when the operation returns no data.

decision

Scoring decision computed for the request when a scoring system applies.

object
status

Decision status from the scoring engine (e.g. pass, fail, refer).

string
score
number
reasons
Array<string>
meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>
data

Raw per-service results; only services enabled for the API key appear.

object
face_liveness_detection
object
key
additional properties
any
active_speaker_detection
object
key
additional properties
any
visual_speech_recognition
object
key
additional properties
any
key
additional properties
any

400

Bad Request / Parameter Validation Failed.

object
error
required
object
code
required
string
invalid_request
message
required

Human-readable message; a string, or a field-error array for validation failures.

meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>

401

Unauthorized / Missing or Invalid Authentication Credentials.

object
error
required
object
code
required
string
invalid_request
message
required

Human-readable message; a string, or a field-error array for validation failures.

meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>

422

Unprocessable Entity / Face not detected, audio unreadable, or file payload syntax error.

object
error
required
object
code
required
string
invalid_request
message
required

Human-readable message; a string, or a field-error array for validation failures.

meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>

500

Internal Server Error.

object
error
required
object
code
required
string
invalid_request
message
required

Human-readable message; a string, or a field-error array for validation failures.

meta
required
object
request_id
required
string
message
string
warnings

Non-fatal caveats about a successful result — for example an enrollment that succeeded but produced a weaker biometric template.

Array<string>