Skip to content
Biometry

API Calls

API Calls Overview

The Biometry API is a RESTful API—which means it allows your application to communicate with Biometry’s services over the internet. It processes data that you send and returns the results in JSON format (a standard format that computers use to share information).

This documentation covers API v2. All gateway endpoints live under the /api-gateway/v2 prefix.

Base URL

All API v2 calls are made to the following base URL: https://api.biometrysolutions.com/api-gateway/v2

Authorization

To use the Biometry API, you must first authenticate your request. This ensures that only authorised users and applications can access the API. You will need an API Token for this, which must be included as a Bearer token in the Authorization header of every request.

Identifying the end user

API v2 identifies the end user with an opaque, customer-provided user_id — any stable string you control (1–128 chars, A-Za-z0-9._:@-). You send it inside a JSON request part rather than a header.

For multipart endpoints (enrollment, verification, face-match, document check), send a form field named request containing a JSON object, alongside the binary file parts:

curl --location 'https://api.biometrysolutions.com/api-gateway/v2/liveness' \
     --header 'Authorization: Bearer <api-key>' \
     --form 'request={"user_id":"user-123","phrase":"one two three four five"}' \
     --form 'video=@"/path/to/video.mp4"'

The request object carries the identity and options for the call (user_id, session_id, phrase, vocabulary, trigger, provider, use_session_video, services, …). Each endpoint page lists the fields it accepts.

Responses

When you send a request to Biometry, the API returns a response in JSON format using a standard success envelope:

{
  "data": { },
  "decision": {
    "status": "pass",
    "score": 0.95,
    "reasons": []
  },
  "meta": {
    "request_id": "fc5605c5-...-87cc-979cd72564d4",
    "message": "human-readable status message"
  }
}
  • data — the endpoint-specific payload (raw service results, extracted document data, etc.). Omitted when the operation returns no data.
  • decision — the scoring decision (status = pass / fail / refer, plus score and reasons). Present only when a scoring system is configured for your API key.
  • meta.request_id — the transaction ID (also returned in the X-Request-Id response header). Use it with Get samples and Result tagging.

Response Codes

The API returns standard response codes:

  • 200 OK: The request was successful.
  • 201 Created: An asynchronous resource (e.g. a deepfake check) was created.
  • 400 Bad Request: Parameter validation failed.
  • 401 Unauthorized: The API token is missing or invalid.
  • 403 Forbidden: A required service is not enabled, or consent is required.
  • 404 Not Found: The requested resource (user, session, reference image, …) does not exist.
  • 422 Unprocessable Entity: The media could not be processed (e.g. no face detected, audio unreadable).
  • 500 Internal Server Error: There was an issue on Biometry’s end.

Handling Response Errors

If something goes wrong, the API returns an error envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "human-readable message, or a field-error array for validation failures"
  },
  "meta": {
    "request_id": "fc5605c5-...-87cc-979cd72564d4"
  }
}

Example Error

If you send a request with an invalid API token:

Terminal window
curl --location 'https://api.biometrysolutions.com/api-gateway/v2/liveness' \
     --header 'Authorization: Bearer eyJh...9JuAXxxJAxkkzk'

Response:

{
  "error": { "code": "unauthorized", "message": "malformed token" },
  "meta": {}
}