Users (v2)

v2 exposes the platform’s view of an end-user under the user_id you chose. There is nothing to create: a user exists as soon as you enroll, verify or consent under that ID. v1 had no equivalent — integrations had to guess from their own database whether a user was enrolled.

Get a user

GET https://api.biometrysolutions.com/api-gateway/v2/users/{user_id}

Authorization

Project API token as Bearer. Only data under the token’s project is visible.

Example

curl 'https://api.biometrysolutions.com/api-gateway/v2/users/8f14e45f-ceea-467a-9f8c-2c963f66afa6' \
     --header 'Authorization: Bearer YOUR_API_TOKEN'

Responses

200

{
  "data": {
    "user_id": "8f14e45f-ceea-467a-9f8c-2c963f66afa6",
    "project_id": "b1d0…",
    "enrollments": { "face": true, "voice": true },
    "face_meta_id": "6f2a…",
    "voice_phrases": ["one two three four five six"]
  },
  "meta": { "request_id": "9e0f…", "message": "user fetched successfully" }
}

Note: An unknown user_id is not a 404: the response comes back with enrollments.face and enrollments.voice both false. Treat that as “no biometrics on file”.

401

{ "error": { "code": "invalid_api_key", "message": "missing authorization token" },
  "meta": { "request_id": "9e0f…" } }

Use this as a pre-flight check to route between onboarding and login, and to skip a verification step the user cannot pass (e.g. no voice enrollment).

Batch user lookup

GET https://api.biometrysolutions.com/api-gateway/v2/users?ids=a,b,c

Query parameters

• ids* (string) — comma-separated user_id values. Maximum 100 per call.

Example

curl 'https://api.biometrysolutions.com/api-gateway/v2/users?ids=8f14e45f,3c6e0b8a,ac3478d6' \
     --header 'Authorization: Bearer YOUR_API_TOKEN'

Responses

200

{
  "data": { "users": [
    { "user_id": "8f14e45f", "project_id": "b1d0…", "enrollments": { "face": true, "voice": false } },
    { "user_id": "3c6e0b8a", "project_id": "b1d0…", "enrollments": { "face": false, "voice": false } }
  ] },
  "meta": { "request_id": "0f1a…" }
}

400

{ "error": { "code": "invalid_request", "message": "ids query parameter supports at most 100 users" },
  "meta": { "request_id": "0f1a…" } }

Reference image

A reference image is a stored portrait for the user — typically the photo from their identity document — that later calls can match against. In v1 these were POST /images and GET /images/{email}; v2 keys them by user_id.

PUT https://api.biometrysolutions.com/api-gateway/v2/users/{user_id}/reference-image

Authorization

Project API token as Bearer. Requires authorization consent recorded for the identity.

Request (multipart/form-data)

• image* (file part) — the portrait to store (JPEG, PNG).

Example

curl --request PUT 'https://api.biometrysolutions.com/api-gateway/v2/users/8f14e45f/reference-image' \
     --header 'Authorization: Bearer YOUR_API_TOKEN' \
     --form 'image=@/path/to/portrait.jpg'

Read it back with:

GET https://api.biometrysolutions.com/api-gateway/v2/users/{user_id}/reference-image

which responds with the raw image bytes (not a JSON envelope), or 404 if no reference image is stored for that user.

Delete enrollments

DELETE https://api.biometrysolutions.com/api-gateway/v2/users/{user_id}/enrollments

Removes the user’s face and voice templates and leaves everything else — their transactions, consents and stored media are untouched.

This is the endpoint to use before re-enrolling somebody. Enrolling a voice over an existing voiceprint merges into it rather than replacing it, so a poor enrollment survives every attempt to correct it by enrolling again. Deleting the templates first is what makes a genuinely fresh enrollment possible.

Not the same as deleting the user

DELETE /v2/users/{user_id} cascades and destroys the audit trail, which makes it the wrong tool for re-enrollment. This endpoint is scoped to the biometric templates and takes a project API token rather than a Console session.

Authorization

Project API token as Bearer.

Example

curl --request DELETE \
     'https://api.biometrysolutions.com/api-gateway/v2/users/8f14e45f-ceea-467a-9f8c-2c963f66afa6/enrollments' \
     --header 'Authorization: Bearer YOUR_API_TOKEN'

Responses

200

{
  "message": "enrollments deleted successfully",
  "data": { "user_id": "8f14e45f-ceea-467a-9f8c-2c963f66afa6", "face": false, "voice": false }
}

500

{ "error": { "code": "internal_error", "message": "failed to delete enrollments" },
  "meta": { "request_id": "1a2b…" } }

Delete a user

DELETE https://api.biometrysolutions.com/api-gateway/v2/users/{user_id}

Cascading delete of everything stored for the user: transactions, consents, face metadata, voice enrollments and uploaded files.

Console session, not an API token

This endpoint requires a Console user session with the project owner or admin role — a project API token gets 401. It is the deletion path the dashboard uses; wire data-subject erasure requests through the Console, or through your own operator tooling authenticated as a Console user.

Responses

200

{ "data": { "deleted": true }, "meta": { "request_id": "1a2b…" } }

401

{ "error": { "code": "invalid_token", "message": "failed to get user claims" },
  "meta": { "request_id": "1a2b…" } }

403

The Console user is not an owner or admin of the project.