Verify face

POST

/v2/face-verify

Verify face from the input video or live image against the user’s enrolled template.

Authorizations

• ApiKeyAuth

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

string format: uuid

nullable

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

Portrait video / image of the user. Always required — this endpoint does not read the session’s stored video.

string format: binary

Responses

200

Face verification completed.

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

object

face_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>

404

Not Found / Specified Resource (User, Session, Reference Image, etc.) does not exist.

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>