How faces attach to a user
Captured during liveness
When a User goes through a session with liveness enabled, Didit captures a selfie, runs passive liveness detection, extracts the largest face, and generates a vector embedding for search.
Stored on the user profile
The face is linked to the session and the parent User entity. The portrait URL surfaces on the user profile as
portrait_image.Face search (1:N)
Face search lets you find a user by uploading an image and matching it against every enrolled face in your application. Use-cases:- Duplicate detection at onboarding — prevent the same person from creating two accounts.
- Reverse lookup — identify the user behind a CCTV frame or an image in a fraud investigation.
- Repeat customer recognition — skip KYC for a returning customer.
POST /v3/face-search/— standalone face search
Duplicate detection
Every new face can be compared against existing enrolled faces to surface duplicates. Didit assigns each face anapproved_duplicate_status:
| Status | Meaning |
|---|---|
NOT_DUPLICATED | No matches found above the similarity threshold |
DUPLICATED | Face matches one or more faces on an already-approved session |
- Decline duplicate-flagged sessions automatically.
- Flag for review — route to a human analyst.
- Warn only — allow but add a risk tag.
Face blocklist
When a session is declined (by rule, analyst, or workflow configuration), the associated face is automatically added to the Face Blocklist for your application. Future sessions with a matching face are rejected.How blocklisting happens
| Trigger | Action |
|---|---|
Session DECLINED and auto-blocklist enabled | Face added to the system face list, user status → BLOCKED |
| Analyst manually blocklists a face from the console | Face added, user status updated per policy |
| Programmatic add via the Lists API | Upload the face image to a face-type blocklist |
Uploading a face to the blocklist
To block a user by face programmatically, upload the face image to a face-type blocklist via the dedicated Upload face to list endpoint. Didit extracts the biometric embedding and inserts it into the matching index — any future session whose liveness selfie matches is auto-declined.There is no direct “attach face to user” public endpoint. Faces attach to users automatically through sessions. To block a user by face, use the Lists API or the console.
Removing a face from the blocklist
Remove the entry from the console at Blocklist → Faces → row actions → Remove, or use the Delete entry endpoint.Face lifecycle summary
Upload a face from the console
Compliance operators can upload faces manually:- Navigate to Users → [user] → Actions → Upload face.
- Select an image; Didit extracts the largest face and stores a new Face record linked to the user.
- Choose whether to enrol into the search index, the blocklist, or both.
- You have a known portrait of a customer verified through an offline channel.
- You want to pre-seed a blocklist with known bad actors from your fraud database.
Privacy and retention
- Face embeddings are numerical vectors, not images. Images themselves are stored in encrypted object storage with signed-URL access.
- Retention follows your application’s data retention policy.
- GDPR / CCPA “right to be forgotten” deletion removes both the image and the embedding from the search index.
Next steps
Face Search
How 1:N face search works.
Liveness
Liveness detection that captures the face.
Blocklist API
Upload a face to a blocklist.
User blocklist
How blocklisting a user works.