Skip to content
Biometry

Match face vs reference

POST
/v2/face-match

Compare the live user image/video against a client-provided reference image.

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
string format: uuid
nullable
use_session_video

Reuse session video from previously uploaded data.

boolean
reference_image
required

Reference portrait image to match against.

string format: binary
video

Captured live video/image. Required unless use_session_video is true, in which case the video stored on the session is reused.

string format: binary

Responses

200

Face matching 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>

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>