Skip to content

Migrating from API v1 to v2

v1 and v2 run side by side against the same projects, API tokens, consents, sessions and dashboards. You can move one call at a time — there is no cut-over and no data migration on your side.

1. Choose the identity value

v1 keys an end-user by X-User-Fullname. v2 uses user_id in the request body. Both resolve to the same identity record, so whatever string you send today as X-User-Fullname is the value to send as user_id — enrollments, consents and history carry over untouched.

If you have been sending real names, this is the moment to switch to an opaque ID. Note that changing the value creates a new identity: the user will need to re-enroll and re-consent under the new ID, so migrate the value deliberately (and only if you can re-onboard).

user_id must match ^[A-Za-z0-9._:@-]{3,128}$. A name containing spaces, or shorter than 3 characters, is rejected with 400 invalid_request.

2. Map the endpoints

v1v2Notes
POST /enroll/facePOST /v2/enrollments/faceFile part renamed to face
POST /enroll/voicePOST /v2/enrollments/voiceFile part renamed to voice; phrase moves into request
POST /process-videoPOST /v2/livenessAnti-spoofing only — see step 4
—POST /v2/face-verifyFace identity check, split out of process-video
—POST /v2/voice-verifyVoice identity check, split out of process-video
POST /match-facesPOST /v2/face-matchimage file part renamed to reference_image
POST /docauth/checkPOST /v2/documents/check
POST /avf/inferPOST /v2/deepfake/checksReturns 201; poll instead of streaming
GET /avf/status/{id}GET /v2/deepfake/checks/{id}Plain JSON read; the v1 SSE stream still exists
POST /sessions/startPOST /v2/sessions
POST /sessions/end/{id}POST /v2/sessions/{id}/end
POST /images / GET /images/{email}PUT / GET /v2/users/{user_id}/reference-imageKeyed by user_id, not email
POST /users/delete/cascadingDELETE /v2/users/{user_id}Console session required, as in v1
—GET /v2/users/{user_id}New: enrollment state for a user
/scores/*/v2/scoring-systems/*Console session; managed from the dashboard
/custom-consents/*/v2/consents/*Same semantics
/api-consent/consent, /api-consent/strg-consentPUT /v2/users/{user_id}/consentsOptional: one call for both consents; the consent service keeps working
/webhooks/*/v2/webhooks/*Console session, as in v1

/api-consent/*, /api-transactions/*, /api-projects/public/apikeys and the warmup endpoints are unversioned and unchanged — keep calling them as you do today, or record consent through v2 with PUT /v2/users/{user_id}/consents.

3. Move headers into the body

Everything that was an X-* business header is now a field in the JSON request part. The old headers are stripped on v2 routes — sending them has no effect.

v1 headerv2 field
X-User-Fullnamerequest.user_id
X-Session-IDrequest.session_id
X-Action-Triggerrequest.trigger
X-Use-Prefilled-Videorequest.use_session_video (boolean, /v2/face-match only)
X-Inhouse-Docauthrequest.provider: inhouse | idscan
X-Inhouse-MRZrequest.mrz_provider: inhouse | idscan
phrase, vocabulary form fieldsrequest.phrase, request.vocabulary

Authorization, X-Request-Id, X-Client-App, X-Client-Version, X-App-Version, X-Device-Info and X-Geo-Location stay headers.

New in v2: request.services.exclude lets a call skip services that are enabled on the token — e.g. {"services": {"exclude": ["visual_speech_recognition"]}} on /v2/liveness. v1 had no request-side equivalent. (The X-Removed-Services response header is unchanged: it still tells you that consent-gated services were dropped from the call.)

Before (v1):

curl 'https://api.biometrysolutions.com/api-gateway/process-video' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'X-User-Fullname: 8f14e45f' \
--header 'X-Session-ID: 0f9c2a1e' \
--form '[email protected]' \
--form 'phrase=one two three four five six'

After (v2):

curl 'https://api.biometrysolutions.com/api-gateway/v2/liveness' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--form 'request={"user_id":"8f14e45f","session_id":"0f9c2a1e","phrase":"one two three four five six"};type=application/json' \

4. Split one process-video call into several

This is one of two behavioural changes, both deliberate. The other is the enrolment model — see step 5, and do not skip it: it is the one that fails silently. In v1, one /process-video call ran every service enabled on your token — anti-spoofing and identity — and returned one blended verdict.

In v2:

  • POST /v2/liveness runs Face Liveness Detection, Active Speaker Detection and Visual Speech Recognition.
  • POST /v2/face-verify runs Face Recognition against the enrolled template.
  • POST /v2/voice-verify runs Voice Recognition against the enrolled template.

Each call returns its own decision. If your v1 integration relied on the single blended scoring_result, you have two options: compose the per-call decisions yourself, or pass the same session_id to every call and read the combined verdict from POST /v2/sessions/{id}/end, which scores every modality captured during the session against the session’s scoring system in one pass. The combined decision fails closed — a session whose scoring system marks a service critical returns refer if that service never ran, so completing only liveness cannot score an accept.

Pass the same session_id to all of them regardless, so the Console still shows one attempt, and set use_session_video: true on the follow-up calls to avoid re-uploading the video. The first call in the session uploads; /v2/liveness, /v2/face-verify, /v2/voice-verify and /v2/face-match all accept the flag and reuse the stored video.

5. Add an explicit enrolment call

What v1 does

A POST /process-video call enrols the user as a side effect when both the authorization consent and the storage consent are on record. When that happens the response carries:

X-Auto-Enroll: true

The enrolment runs after the verification response is sent, so it never delays or fails the call. What it attempts:

attempted whenskipped when
Facealwaysliveness failed, or the user already has a face template
Voicethe call carried audio, a user identity and a phrasethe phrase is under the 7-word minimum, the identity is empty, or the user already has a voiceprint

Because it skips users who are already enrolled, the steady state for a returning user is “attempted, skipped” — the enrolment happens once, on the first verification that satisfies the consents.

What v2 does

Nothing. /v2/liveness, /v2/face-verify and /v2/voice-verify match against existing templates and never create or train them. Enrolment on v2 happens only through the explicit /v2/enrollments/* routes. This is deliberate: it makes enrolment an auditable action a caller asks for, rather than a consent-dependent side effect of a verification.

The X-Auto-Enroll response header is v1-only and is never set on v2. In the first-party SDKs, the field that surfaced it (autoEnrolled and equivalents) was removed in the v2 releases.

What to do instead

Add an explicit enrolment call after a successful first verification:

# 1. verify — same as before, minus the implicit enrolment
curl 'https://api.biometrysolutions.com/api-gateway/v2/liveness' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--form 'request={"user_id":"8f14e45f","session_id":"0f9c2a1e"};type=application/json' \
# 2. enrol — explicit, once per user, reusing the video from step 1
curl 'https://api.biometrysolutions.com/api-gateway/v2/enrollments/face' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'X-Session-ID: 0f9c2a1e' \
--form 'request={"user_id":"8f14e45f","use_session_video":true};type=application/json'

use_session_video enrols from the video the liveness step already stored on the session, so a liveness-then-enrol flow still uploads one video — the same single upload v1 auto-enrolment gave you. Enrol before ending the session; once /v2/sessions/{id}/end has been called the request answers 409. Without it, send a face image as a face file part instead. See Face Enrollment for the full contract.

Both consents are required on /v2/enrollments/face too, so the precondition is unchanged — only the explicitness is. Use GET /v2/users/{user_id} to check whether a user already holds templates rather than enrolling blindly on every verification.

Voice is not a like-for-like swap. v1 auto-enrolment built a voiceprint from the single utterance in the verification call; POST /v2/enrollments/voice expects several distinct recordings of the phrase, because one is not enough for a reliable voiceprint. If you relied on v1 auto-enrolling voice, treat v2 as requiring a real enrolment step, not a one-line substitution.

6. Update response parsing

v1v2
data["Face Liveness Detection"]data.face_liveness_detection
data["Active Speaker Detection"]data.active_speaker_detection
data["Visual Speech Recognition"]data.visual_speech_recognition
data["Face Recognition"]data.face_recognition
data["Voice Recognition"]data.voice_recognition
scoring_result (string or object)decision.status
scoredecision.score
decision_reasonsdecision.reasons
messagemeta.message
{"error": "text"}{"error": {"code": "…", "message": "…"}, "meta": {"request_id": "…"}}

Scores keep the 0–100 scale and the per-service payloads (code, description, result, score) are unchanged — only the keys and the wrapper move. See the Error catalog for the new codes.

7. What is not in v2 yet

  • No per-modality unenroll. DELETE /v2/users/{user_id}/enrollments drops the user’s face and voice templates together. There is no way to remove one and keep the other — but you no longer have to delete the whole user to do it, which was the v1 position.

Keep using the v1 endpoint where this matters to you; v1 is not going away without an announced deprecation window, Deprecation/Sunset headers and notice on this portal.

Scoring systems

Scoring configuration moved under /v2/scoring-systems with versioned reads.

Operationv1v2
ListGET /api-gateway/scoresGET /api-gateway/v2/scoring-systems
CreatePOST /api-gateway/scoresPOST /api-gateway/v2/scoring-systems
ReadGET /api-gateway/scores/{id}GET /api-gateway/v2/scoring-systems/{id}
UpdatePATCH /api-gateway/scores/{id}PATCH /api-gateway/v2/scoring-systems/{id}
DeleteDELETE /api-gateway/scores/{id}DELETE /api-gateway/v2/scoring-systems/{id}
Read a past versionGET /api-gateway/scores/{id}/{version}GET /api-gateway/v2/scoring-systems/{id}/versions/{version}
Project defaultGET /api-gateway/scores/defaultGET /api-gateway/v2/scoring-systems/default
Create from a presetPOST /api-gateway/scores/default/{project_id}POST /api-gateway/v2/scoring-systems/presets/default
Dry-run against a payloadPOST /api-gateway/scores/test/{scores_id}POST /api-gateway/v2/scoring-systems/{id}/test