Skip to content

Verification

The v1 process-video endpoint has been split, in API v2, into three focused verification endpoints:

EndpointPurposeServices
POST /v2/livenessAnti-spoof / liveness on a captured videoFace Liveness Detection, Active Speaker Detection, Visual Speech Recognition
POST /v2/face-verifyVerify a face against the user’s enrolled templateFace Recognition
POST /v2/voice-verifyVerify a voice against the user’s enrolled templateVoice 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/liveness

request part fields

FieldTypeDescription
user_id*stringOpaque, customer-provided identity key.
phrasestringThe 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_idstringOptional. Link this transaction to a session.
triggerstringOptional. Contextual trigger event name (e.g. authentication).
vocabularystringOptional. Speech-recognition vocabulary; defaults to en_digits.
services.excludestring[]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-verify

request part fields

FieldTypeDescription
user_id*stringOpaque, customer-provided identity key.
phrasestringOptional and unused: face verification runs Face Recognition only, which takes no phrase.
session_idstringOptional. Reuse the session’s stored video by omitting the video part and setting use_session_video.
use_session_videobooleanOptional. 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_video is true.
{
"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-verify

request part fields

FieldTypeDescription
user_id*stringOpaque, customer-provided identity key.
phrase*stringThe 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_idstringOptional. Reuse the session’s stored video by omitting the voice part and setting use_session_video.
use_session_videobooleanOptional. 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_video is true.
{
"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": {} }