Skip to content

Enroll face

POST
/v2/enrollments/face

Enroll face for face recognition. Requires user_id in request.

Supply the face either as a face image file or, with use_session_video: true, from the liveness video the session already holds — so a liveness→enroll flow uploads one video instead of two. There is no implicit enrollment on v2: verification endpoints never create or train a template.

Requires the user’s authorization and storage consent, recorded with PUT /v2/users/{user_id}/consents; without them the call returns 403.

Authorizations

Request Body required

object
request
required
object
user_id
required

Opaque, customer-provided identity key.

string
>= 3 characters <= 128 characters /^[A-Za-z0-9._:@-]+$/
session_id

The session whose stored liveness video to enroll from. Required when use_session_video is true; the session must still be open.

string format: uuid
nullable
use_session_video

Enroll from the liveness video stored on the session named by session_id instead of an uploaded image. The face part is then not required and is ignored. Cannot be combined with is_document. Not offered on /v2/enrollments/voice: a voiceprint needs several distinct takes and a session holds one video.

boolean
face

Face image file (e.g. JPEG, PNG). Required unless use_session_video is true.

string format: binary

Responses

200

Face enrolled. A rejected enrollment is reported as 400 on v2, so a 200 here means the template was created; data.enrollment_result carries the provider’s detail.

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
enrollment_result
object
code

0 on success. 1 no face / too small / bad quality, 2 more than one face, 3 face not centered.

integer
description
string
key
additional properties
any
document_auth
object
first_name
string
last_name
string
birth_date
string format: date
document_number
string
expiry_date
string format: date
country_code
string
document_category
string
current_result
string
portrait_photo
string
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>

403

Forbidden / Service Not Enabled or Consent Required.

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>

409

The session has already ended, so its video can no longer be enrolled from. Enroll before calling /v2/sessions/{id}/end.

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>