API v1 endpoint reference (deprecated)

v1 is deprecated

API v2 is the supported surface. This page exists because the v1 routes still respond and real integrations still call them — it is a lookup table for operating an existing v1 integration, not a guide for building a new one.

If you are starting now, begin at Quick Start and ignore this page. If you are moving an integration across, the v1 → v2 migration guide is the page you want; this one only tells you what v1 does today.

Every path below is relative to your gateway host, e.g. https://api.biometrysolutions.com/api-gateway/process-video.

Two authorization models

v1 endpoints are split between two kinds of caller, and the split is not obvious from the paths.

Marked	Credential	Who calls it
API token	Authorization: Bearer <your API token>	your application, server-side
Console session	dashboard session cookie/JWT	the Biometry Console, or a script acting as a signed-in user

Console-session endpoints are management operations. They are documented here for completeness, but they are not part of an application integration and several additionally require the Owner or Admin project role.

v1 also carries business parameters as X-* request headers where v2 puts them in a JSON request part. See step 3 of the migration guide for the full header → field mapping.

Verification and enrolment

Method	Path	Auth	What it does	v2
POST	/api-gateway/process-video	API token	Runs every service enabled on the token in one call — liveness and identity — and returns one blended verdict. Consent-gated services are dropped from the call rather than failing it; the dropped list comes back in X-Removed-Services. Also enrols the user as a side effect when both consents are on record — see the enrolment model.	/v2/liveness, /v2/face-verify, /v2/voice-verify
POST	/api-gateway/enroll/face	API token	Enrols a face template. Requires authorization and storage consent.	/v2/enrollments/face
POST	/api-gateway/enroll/voice	API token	Enrols a voiceprint. Requires authorization and storage consent.	/v2/enrollments/voice
POST	/api-gateway/match-faces	API token	Compares a face in a video against a supplied reference image.	/v2/face-match

Documents and deepfake

Method	Path	Auth	What it does	v2
POST	/api-gateway/docauth/check	API token	Checks an identity document’s authenticity. Provider selected with X-Inhouse-Docauth / X-Inhouse-MRZ.	/v2/documents/check
POST	/api-gateway/avf/infer	API token	Submits a video for Anti-Video Forgery (deepfake) inference.	POST /v2/deepfake/checks
GET	/api-gateway/avf/status/{request_id}	API token	Reads inference status. The v1 route streams; the v2 route is a plain JSON read.	GET /v2/deepfake/checks/{request_id}

Reference images

Method	Path	Auth	What it does	v2
POST	/api-gateway/images	API token	Stores a user’s reference image. Requires authorization consent.	PUT /v2/users/{user_id}/reference-image
GET	/api-gateway/images/{email}	API token	Reads the stored reference image. Keyed by email, where v2 is keyed by user_id.	GET /v2/users/{user_id}/reference-image

Sessions

Method	Path	Auth	What it does	v2
POST	/api-gateway/sessions/start	API token	Opens a session so several calls group into one Console entry.	POST /v2/sessions
POST	/api-gateway/sessions/end/{id}	API token	Closes a session.	POST /v2/sessions/{id}/end — which additionally returns a combined decision across the session’s steps, something the v1 route does not do
GET	/api-gateway/sessions/{id}	Console session	Reads one session.	GET /v2/sessions/{id}
POST	/api-gateway/sessions/list	Console session	Lists sessions.	GET /v2/sessions

Users

Method	Path	Auth	What it does	v2
GET	/api-gateway/internal/users/{unique_id}/face-enrollment	Console session	Reads whether a user holds a face template.	GET /v2/users/{user_id}, which reports enrolment state for both modalities
POST	/api-gateway/users/delete/cascading	Console session, Owner or Admin	Deletes a user and everything attached to them.	DELETE /v2/users/{user_id}
POST	/api-gateway/admin/users/delete/cascading	Console session, Admin	Same, for cross-project administration.	—
POST	/api-gateway/apikeys/info	Console session	Batch-reads API key metadata.	—

v1 has no equivalent of DELETE /v2/users/{user_id}/enrollments, which drops a user’s templates without deleting the user.

Consents

v1 calls these “custom consents”. The semantics are unchanged in v2 — only the path and the update verb.

Method	Path	Auth	v2
POST	/api-gateway/custom-consents	Console session, Owner or Admin	POST /v2/consents
GET	/api-gateway/custom-consents/{id}	Console session	GET /v2/consents/{id}
PATCH	/api-gateway/custom-consents/append/{id}	Console session, Owner or Admin	PATCH /v2/consents/{id}
POST	/api-gateway/custom-consents/{id}/approve/{user_id}	API token	POST /v2/consents/{id}/approve/{user_id}
GET	/api-gateway/custom-consents/my-approvals/{user_id}	API token	GET /v2/consents/my-approvals/{user_id}

The two consents a verification checks — authorization and storage — are separate from these and are recorded through the unversioned /api-consent/* service. See Consent.

Scoring systems

All console-session, all additionally requiring accepted terms. Owner or Admin role where noted.

Method	Path	Role	v2
POST	/api-gateway/scores	Owner or Admin	POST /v2/scoring-systems
GET	/api-gateway/scores	any	GET /v2/scoring-systems
GET	/api-gateway/scores/all	any	GET /v2/scoring-systems/all
POST	/api-gateway/scores/info	any	POST /v2/scoring-systems/info
GET	/api-gateway/scores/{scores_id}	any	GET /v2/scoring-systems/{id}
GET	/api-gateway/scores/{scores_id}/{version}	any	GET /v2/scoring-systems/{id}/versions/{version}
PATCH	/api-gateway/scores/{scores_id}	Owner or Admin	PATCH /v2/scoring-systems/{id}
DELETE	/api-gateway/scores/{scores_id}	Owner or Admin	DELETE /v2/scoring-systems/{id}
POST	/api-gateway/scores/test/{scores_id}	any	POST /v2/scoring-systems/{id}/test
GET	/api-gateway/scores/default	—	GET /v2/scoring-systems/default

GET /scores/default returns the built-in preset and is the one scoring route that takes no session.

Scoring systems are normally managed from the Console rather than over the API. See Scoring systems.

Webhooks

All console-session, all requiring accepted terms.

Method	Path	Role	v2
POST	/api-gateway/webhooks	Owner or Admin	POST /v2/webhooks
GET	/api-gateway/webhooks	any	GET /v2/webhooks
GET	/api-gateway/webhooks/{id}	any	GET /v2/webhooks/{id}
PATCH	/api-gateway/webhooks/{id}	Owner or Admin	PATCH /v2/webhooks/{id}
DELETE	/api-gateway/webhooks/{id}	Owner or Admin	DELETE /v2/webhooks/{id}
POST	/api-gateway/webhooks/{id}/rotate-secret	Owner or Admin	POST /v2/webhooks/{id}/rotate-secret
GET	/api-gateway/webhooks/{id}/deliveries	any	GET /v2/webhooks/{id}/deliveries
POST	/api-gateway/webhooks/{id}/deliveries/{delivery_id}/retry	Owner or Admin	—

Operational endpoints

Unversioned, and identical whichever API version you call.

Method	Path	Auth	What it does
GET	/api-gateway/health/live	none	Liveness probe.
GET	/api-gateway/health/ready	none	Readiness probe, including dependency checks.
GET	/api-gateway/health/metrics	none	Metrics snapshot.
POST	/api-gateway/warmup	none	Pre-warms the ML services. See Warmup.
GET	/api-gateway/warmup/status	none	Reads warmup progress.

Response shape

v1 returns a flat envelope with human-readable service names as keys:

{
  "data": {
    "Face Liveness Detection": { "code": 0, "description": "…", "result": "…", "score": 98 },
    "Face Recognition":        { "code": 0, "description": "…", "result": "…", "score": 95 }
  },
  "scoring_result": "accept",
  "score": 96,
  "decision_reasons": [],
  "message": "…"
}

Errors are a bare string: {"error": "text"}.

Both changed in v2 — snake_case service keys, a decision object, and a structured error envelope with a machine-readable code. See step 6 of the migration guide and the Error catalog.

Response headers

Header	Versions	Meaning
X-Removed-Services	v1 and v2	Services dropped from this call because a required consent was missing.
X-Auto-Enroll	v1 only	The call also enrolled the user. Never set on v2, which does not enrol as a side effect.