Prembly
GuidesAPI Reference
BiometricsIdentify a face POST
POST
/api/v1/verification/biometrics/face/identify/

Searches one of your galleries for a live face (1:N) and returns the closest enrolled subjects.

The gallery search ranks candidates by similarity. With confirm: true (the default) the top three are each compared again against their enrolled image and scored by confidence; best_match is the highest candidate at or above confidence_threshold. With confirm: false there is no second check and best_match is simply the nearest candidate, so treat it as a lead, not proof. Candidates beyond the top three are never confirmed and have a null confidence.

Finding nobody is a valid, billed result: matched is false and candidates is empty. Only your own galleries are searched.

Billed per completed search and debited from the organisation wallet. Sandbox keys return a sample match.

Authorization

ApiKeyAuth
X-API-Key<token>

In: header

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/api/v1/verification/biometrics/face/identify/" \  -H "Content-Type: application/json" \  -d '{    "image": "<base64 live face image>",    "top_k": 5,    "confidence_threshold": 85  }'
{  "reference_id": "VER-BIOMETRIC_FACE_IDENTIFY-X4N7RB9PEA",  "gallery_id": "default",  "matched": true,  "confirmed": true,  "best_match": {    "subject_id": "cust-1042",    "similarity": 0.9132,    "confidence": 93.4,    "is_match": true  },  "candidates": [    {      "subject_id": "cust-1042",      "similarity": 0.9132,      "confidence": 93.4,      "is_match": true    },    {      "subject_id": "cust-2210",      "similarity": 0.7411,      "confidence": 41,      "is_match": false    }  ]}
Response Codes & Statuses: Prembly API responses include custom response_code values (e.g., 00 Success, 01 Not Found, 02 Unavailable).
View Response Codes Guide
Prembly Slack Community

Join our developer Slack channel for real-time integration support, engineering updates, and direct Q&A with the Prembly team.

Join Slack Channel

Erase an enrolled face DELETE

Permanently removes a subject's stored image and face data. Use it for erasure requests and when a customer leaves. Erasure is all or nothing: if either store cannot be cleared the call returns `503` and keeps the enrolment, so you can safely retry until it succeeds. To replace a face instead, enrol again with `overwrite: true`. Not billed.

Verify an enrolled face POST

Checks a live image against one enrolled subject (1:1) and reports whether it is the same person. Use this when you know who the person claims to be. It is cheaper and more accurate than **Identify a face**. A non-match (`is_match: false`) is a valid, billed result, not an error. Raise `confidence_threshold` for higher-risk actions such as large transfers. Returns `404` if the subject is not enrolled, without charging. Billed per completed comparison and debited from the organisation wallet. Sandbox keys return a sample match.