Biometrics
Prembly's Biometrics channels answer a question that no registry lookup can: is the person presenting this identity the person it belongs to, and are they physically present?
A record lookup confirms that an identifier exists and returns the demographics attached to it. Biometrics binds that record to a live human being — comparing a submitted selfie against a registry photo or document portrait, and scoring whether the submitted image came from a real face rather than a printout, a screen, or a mask.
1. Three Surfaces
Biometrics is delivered through three surfaces. They differ most importantly in whether Prembly stores anything on your behalf.
| Surface | What it does | Stores a face? |
|---|---|---|
| Stateless channels | Compare two images, or score whether one image came from a live person | No |
| Face-bound verification | Performs a registry or document lookup and a face match in a single billed call | No |
| Face Gallery | Enrols faces into your own private gallery, then authenticates (1:1) or identifies (1:N) against it | Yes, until you erase it |
The first two are covered in Verification Channels; the third in Face Gallery.
Underneath them sit four primitives:
| Operation | What it answers | Where |
|---|---|---|
| Face Comparison (1:1) | Are these two images the same person? | image_comparison |
| Liveness Detection | Was this image captured from a live person? | liveliness_check |
| Face-Bound Verification | Does this registry or document record belong to the person in this selfie? | bvn_w_face, nin_w_face, document_w_face |
| Gallery Search (1:N) | Who, among the faces I have enrolled, is this? | Face Gallery identify |
2. Choosing a Surface
| If you need to… | Use |
|---|---|
| Confirm a returning user matches a reference photo you already hold | image_comparison |
| Prove a capture came from a live person, with no reference photo | liveliness_check |
| Onboard a Nigerian customer against the banking registry | bvn_w_face |
| Onboard a Nigerian customer against the national ID registry | nin_w_face |
| Onboard in a market without registry access, or against a passport | document_w_face |
| Re-authenticate a known customer repeatedly over time | Face Gallery enroll, then verify |
| Recognise someone who has not told you who they are | Face Gallery identify |
A typical onboarding flow chains two of these: run liveliness_check on the captured selfie to reject spoofs before spending a billed registry call, then pass the same image to bvn_w_face, nin_w_face, or document_w_face for the bound lookup.
If you expect to re-authenticate the same person later — a returning app login, a branch visit, a high-value transfer — enrol them into a gallery during onboarding. Every subsequent check is then a single verify call against a face you already trust, with no registry lookup to pay for.
To screen a face against prior fraud reports rather than against your own records, see the Fraud Lens guide.
3. Interpreting Scores
Biometric operations return scores rather than pass/fail verdicts, and the normalisation differs between them. Read the field, not the magnitude.
| Field | Range | Produced by |
|---|---|---|
confidence | Varies by channel — some 0–1, some 0–100 | Face comparison, face-bound channels, gallery verify |
confidence_in_percentage | 0–100 | liveliness_check |
similarity | 0–1 | Gallery identify, from the vector search |
The gallery distinction catches people out: in an identify response, similarity is how close the search found a candidate, while confidence is the result of re-comparing that candidate against its enrolled image. They are different measurements on different scales, and the second is the one to trust. See Face Gallery.
Set thresholds against your own risk posture
There is no universal cut-off. A high-value lending flow and a low-value wallet top-up warrant different thresholds on the same channel. Before going live, run a sample of your real capture conditions through sandbox, plot the score distribution for known-good and known-bad pairs, and pick the threshold that lands your false-accept and false-reject rates where your risk team wants them.
Route borderline scores to manual review rather than auto-rejecting them. Biometric capture quality varies with lighting, camera hardware, and user behaviour, and a rejected genuine customer is a churn event.
4. Billing and Error Handling
Biometric operations are billed per call, and a face mismatch is a successful verification, not a failure. A call that returns "message": "No Match", or a gallery verify that returns is_match: false, has done its job and is billed accordingly. Only transport errors and rejected requests are not billed.
| Code | Meaning | Recommended Action |
|---|---|---|
200 | Verification completed — read face_data, confidence, or is_match for the result. | Apply your threshold and decide. |
400 | Invalid request data — malformed base64, unsupported image format, unreachable URL, or a field failing its pattern. | Validate the image client-side before submitting; surface a re-capture prompt. |
401 | Invalid or missing API key. | Check the X-API-Key header and that the key matches the environment. |
402 | Insufficient wallet balance. Nothing was done or charged. | Top up; see Billing. |
422 | Image problem — no face detected, unreadable image, or a failed liveness check. | Prompt for a re-capture. |
Image payloads are substantially larger than the identifier-only channels. Set a generous client timeout, compress captures before encoding, and prefer URL submission over inline base64 for images above roughly 1 MB.
5. Capturing Images in Your App
You do not have to build the capture flow yourself. The Prembly SDK ships a hosted verification interface with face capture and liveness built in, including optional gesture-based liveness, and returns the result to your backend.
- Web SDK
- React Native SDK
- Flutter SDK
- Backend and webhooks — for receiving the outcome server-side
Reach for the API directly when you control the capture surface yourself and need the raw scores.