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
| v1 | v2 | Notes |
|---|---|---|
POST /enroll/face | POST /v2/enrollments/face | File part renamed to face |
POST /enroll/voice | POST /v2/enrollments/voice | File part renamed to voice; phrase moves into request |
POST /process-video | POST /v2/liveness | Anti-spoofing only — see step 4 |
| — | POST /v2/face-verify | Face identity check, split out of process-video |
| — | POST /v2/voice-verify | Voice identity check, split out of process-video |
POST /match-faces | POST /v2/face-match | image file part renamed to reference_image |
POST /docauth/check | POST /v2/documents/check | |
POST /avf/infer | POST /v2/deepfake/checks | Returns 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/start | POST /v2/sessions | |
POST /sessions/end/{id} | POST /v2/sessions/{id}/end | |
POST /images / GET /images/{email} | PUT / GET /v2/users/{user_id}/reference-image | Keyed by user_id, not email |
POST /users/delete/cascading | DELETE /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-consent | PUT /v2/users/{user_id}/consents | Optional: 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 header | v2 field |
|---|---|
X-User-Fullname | request.user_id |
X-Session-ID | request.session_id |
X-Action-Trigger | request.trigger |
X-Use-Prefilled-Video | request.use_session_video (boolean, /v2/face-match only) |
X-Inhouse-Docauth | request.provider: inhouse | idscan |
X-Inhouse-MRZ | request.mrz_provider: inhouse | idscan |
phrase, vocabulary form fields | request.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 '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/livenessruns Face Liveness Detection, Active Speaker Detection and Visual Speech Recognition.POST /v2/face-verifyruns Face Recognition against the enrolled template.POST /v2/voice-verifyruns 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: trueThe enrolment runs after the verification response is sent, so it never delays or fails the call. What it attempts:
| attempted when | skipped when | |
|---|---|---|
| Face | always | liveness failed, or the user already has a face template |
| Voice | the call carried audio, a user identity and a phrase | the 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 enrolmentcurl '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 1curl '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
| v1 | v2 |
|---|---|
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 |
score | decision.score |
decision_reasons | decision.reasons |
message | meta.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}/enrollmentsdrops 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.
| Operation | v1 | v2 |
|---|---|---|
| List | GET /api-gateway/scores | GET /api-gateway/v2/scoring-systems |
| Create | POST /api-gateway/scores | POST /api-gateway/v2/scoring-systems |
| Read | GET /api-gateway/scores/{id} | GET /api-gateway/v2/scoring-systems/{id} |
| Update | PATCH /api-gateway/scores/{id} | PATCH /api-gateway/v2/scoring-systems/{id} |
| Delete | DELETE /api-gateway/scores/{id} | DELETE /api-gateway/v2/scoring-systems/{id} |
| Read a past version | GET /api-gateway/scores/{id}/{version} | GET /api-gateway/v2/scoring-systems/{id}/versions/{version} |
| Project default | GET /api-gateway/scores/default | GET /api-gateway/v2/scoring-systems/default |
| Create from a preset | POST /api-gateway/scores/default/{project_id} | POST /api-gateway/v2/scoring-systems/presets/default |
| Dry-run against a payload | POST /api-gateway/scores/test/{scores_id} | POST /api-gateway/v2/scoring-systems/{id}/test |