Verification
The v1 process-video endpoint has been split, in API v2, into three focused verification endpoints:
| Endpoint | Purpose | Services |
|---|---|---|
POST /v2/liveness | Anti-spoof / liveness on a captured video | Face Liveness Detection, Active Speaker Detection, Visual Speech Recognition |
POST /v2/face-verify | Verify a face against the user’s enrolled template | Face Recognition |
POST /v2/voice-verify | Verify a voice against the user’s enrolled template | Voice Recognition |
All three take an opaque user_id in the JSON request part (see API Calls), plus a media file. Liveness and voice verification also take the spoken phrase; face verification runs face recognition only and takes no phrase. They return the standard success envelope, and — when a scoring system is configured for your API key — a decision object.
Requirements for the video
The user records a short video where they show their face and say a set of numbers out loud. The services compare the numbers in the phrase field with what the user says in the video.
Where phrase comes from
The digits are a challenge your backend issues: we recommend 8 distinct digits from 1–9, from a secure random source, stored against the user’s login attempt, valid for at most 5 minutes and used once. The device only displays them. Send your backend’s stored copy as phrase, never a phrase the device returns. If the device decides the phrase, someone can replay a pre-recorded video of the user together with whatever digits that video happens to say, and the lip-reading and voice checks will agree. See Liveness challenge for the rules and Node and Go examples.
In the v2 JSON request part, phrase may be the digit string ("48719352") or the digits spelled out ("four eight seven one nine three five two"): v2 spells digits out before comparing. The legacy v1 /process-video endpoint does not, so send it the spelled-out words.
These endpoints don’t reject a short phrase, but the voice engine’s quality check needs at least 7 recognised words: voice enrollment rejects a shorter phrase, and voice auto-enrollment silently skips it. Issue 8 digits so one misheard digit still leaves 7, and record for about 10 seconds.
Authorization
These endpoints require an API token as Bearer in the Authorization header. Go to Authorization guide for details.
Liveness
Request
POST https://api.biometrysolutions.com/api-gateway/v2/livenessrequest part fields
| Field | Type | Description |
|---|---|---|
user_id* | string | Opaque, customer-provided identity key. |
phrase | string | The challenge the user reads out loud in the video: your backend’s stored copy (we recommend 8 digits). See Where phrase comes from. Required when Visual Speech Recognition runs, which it does unless you exclude it or it is not enabled on your API key; a missing phrase is then rejected with 400 invalid_request. |
session_id | string | Optional. Link this transaction to a session. |
trigger | string | Optional. Contextual trigger event name (e.g. authentication). |
vocabulary | string | Optional. Speech-recognition vocabulary; defaults to en_digits. |
services.exclude | string[] | Optional. Services to skip: face_liveness_detection, active_speaker_detection, visual_speech_recognition, face_recognition, voice_recognition. |
File parts
- video* (formData file) — the captured video.
Sample
curl --location 'https://api.biometrysolutions.com/api-gateway/v2/liveness' \ --header 'Authorization: Bearer eyJhbGciO...ANYea8r2xOG-Urc' \ --form 'request={"user_id":"user-123","phrase":"48719352"}' \ --form 'video=@"/[path to your file]/video.mp4"'{ "data": { "face_liveness_detection": { "code": 0, "description": "Successful check", "result": true, "score": 76.65 }, "active_speaker_detection": { "code": 0, "description": "Successful check", "result": 97.79, "score": 98.77 }, "visual_speech_recognition": { "code": 0, "description": "Successful check", "result": "FOUR EIGHT SEVEN ONE NINE THREE FIVE TWO", "score": 88.64 } }, "decision": { "status": "pass", "score": 0.91, "reasons": [] }, "meta": { "request_id": "fc5605c5-...-87cc-979cd72564d4", "message": "liveness analysis complete" }}Face verification
Verifies the face in the video/image against the user’s enrolled face template. The user must have been enrolled first via Face Enrollment. It runs face recognition only, so the request takes no phrase.
Request
POST https://api.biometrysolutions.com/api-gateway/v2/face-verifyrequest part fields
| Field | Type | Description |
|---|---|---|
user_id* | string | Opaque, customer-provided identity key. |
phrase | string | Optional and unused: face verification runs Face Recognition only, which takes no phrase. |
session_id | string | Optional. Reuse the session’s stored video by omitting the video part and setting use_session_video. |
use_session_video | boolean | Optional. Reuse the video captured earlier in the session instead of uploading one. Requires session_id; without it the request is rejected with 400 invalid_request. |
File parts
- video (formData file) — required unless
use_session_videoistrue.
{ "data": { "face_recognition": { "code": 0, "description": "Successful check", "score": 61.52 } }, "decision": { "status": "pass", "score": 0.88, "reasons": [] }, "meta": { "request_id": "fc5605c5-...", "message": "face verification completed" }}Voice verification
Verifies the voice against the user’s enrolled voice template (see Voice Enrollment).
Request
POST https://api.biometrysolutions.com/api-gateway/v2/voice-verifyrequest part fields
| Field | Type | Description |
|---|---|---|
user_id* | string | Opaque, customer-provided identity key. |
phrase* | string | The challenge the user reads out loud: your backend’s stored copy (we recommend 8 digits). See Where phrase comes from. A missing phrase is rejected with 400 invalid_request. |
session_id | string | Optional. Reuse the session’s stored video by omitting the voice part and setting use_session_video. |
use_session_video | boolean | Optional. Reuse the video captured earlier in the session instead of uploading one. Requires session_id; without it the request is rejected with 400 invalid_request. |
File parts
- voice (formData file) — audio/video containing the user’s speech. Required unless
use_session_videoistrue.
{ "data": { "voice_recognition": { "status": "good", "id": "user-123", "score": 0.99, "imposter_prob": 0.01, "log_odds": "1.0" } }, "decision": { "status": "pass", "score": 0.95, "reasons": [] }, "meta": { "request_id": "fc5605c5-...", "message": "voice verification completed" }}Error responses
{ "error": { "code": "invalid_request", "message": "user_id is required" }, "meta": {} }{ "error": { "code": "face_not_detected", "message": "no face detected in the video" }, "meta": {} }{ "error": { "code": "internal_error", "message": "string" }, "meta": {} }