Face Enrollment

Enroll a face for face recognition.

Authorization

This endpoint requires an API token as Bearer in the Authorization header. Go to Authorization guide for details.

Request (POST)

POST https://api.biometrysolutions.com/api-gateway/v2/enrollments/face

Headers

Authorization* - Your API Token.
X-Session-ID — the session to enroll from. Required when use_session_video is true.

`request` part fields

Field	Type	Description
`user_id`*	string	Opaque, customer-provided identity key for the user being enrolled.
`is_document`	boolean	Optional. Set to `true` if the uploaded image is a document photo (passport / driver’s license).
`use_session_video`	boolean	Optional. Enroll from the liveness video already stored on the session instead of uploading an image. Requires `X-Session-ID`, and the session must still be open. Cannot be combined with `is_document`.

File parts

face (Image file) — a JPEG, PNG, or JPG image of the face. Required unless use_session_video is true.

Enrolling from the session video

There is no implicit enrollment on v2: /v2/liveness, /v2/face-verify and /v2/voice-verify never create or train a template. A flow that captures a video for liveness and then enrolls the user from it does not have to upload that video twice — set use_session_video and the enrollment reuses the video the liveness step already stored on the session.

# 1. capture once
curl --location 'https://api.biometrysolutions.com/api-gateway/v2/sessions' \
     --header 'Authorization: Bearer <token>'
# → { "data": { "session_id": "sess-123" }, ... }

curl --location 'https://api.biometrysolutions.com/api-gateway/v2/liveness' \
     --header 'Authorization: Bearer <token>' \
     --header 'X-Session-ID: sess-123' \
     --form 'request={"user_id":"user-123"}' \
     --form 'video=@"[path_to_video]/capture.mp4"'

# 2. enroll from that same video — no second upload
curl --location 'https://api.biometrysolutions.com/api-gateway/v2/enrollments/face' \
     --header 'Authorization: Bearer <token>' \
     --header 'X-Session-ID: sess-123' \
     --form 'request={"user_id":"user-123","use_session_video":true}'

Both the authorization and storage consents are required, as on any enrollment. Enroll before ending the session: once /v2/sessions/{id}/end has been called the stored video can no longer be enrolled from, and the request answers 409.

This is face-only. /v2/enrollments/voice does not accept use_session_video: a voiceprint is built from several distinct recordings of the phrase and a session holds a single video, so reusing it would produce a one-utterance print that verifies poorly.

Responses

The success envelope. data.enrolled is true on success.

Response sample:

{
  "data": { "enrolled": true, "user_id": "user-123" },
  "meta": { "request_id": "fc5605c5-...", "message": "face enrolled successfully" }
}

{ "error": { "code": "invalid_request", "message": "user_id is required" }, "meta": {} }

Only when use_session_video is true.

{ "error": { "code": "conflict", "message": "session has already ended; enroll from the session video before calling /v2/sessions/{id}/end" }, "meta": {} }

{ "error": { "code": "face_not_detected", "message": "no face detected, too small, or bad quality" }, "meta": {} }

Sample

Request

curl --location 'https://api.biometrysolutions.com/api-gateway/v2/enrollments/face' \
     --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhbGciO...ANYea8r2xOG-Urc' \
     --form 'request={"user_id":"user-123"}' \
     --form 'face=@"[path_to_image_file]/face.png"'

Response

{
  "data": { "enrolled": true, "user_id": "user-123" },
  "meta": { "request_id": "fc5605c5-...", "message": "face enrolled successfully" }
}