Faces and Biometrics

Face biometrics are central to every User entity. Didit captures a face during liveness detection, generates a vector embedding, and stores it for four downstream features: 1:N face search, duplicate detection, blocklist enforcement, and biometric re-authentication.

Stored faces double as the reference for Biometric Authentication: create a biometric-auth session with the user’s vendor_data and omit portrait_image, and Didit reuses the stored face automatically (approved liveness face first, then the ePassport chip photo, then the ID document portrait, then a manually enrolled profile face).

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.

Indexed for search

The embedding is added to the search index. Subsequent sessions can run 1:N searches against this index.

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.

Face search runs automatically during new sessions when your workflow has duplicate detection enabled. It is also exposed as a standalone API:

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 an approved_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

Workflows can be configured to:

Decline duplicate-flagged sessions automatically.
Flag for review — route to a human analyst.
Warn only — allow but add a risk tag.

Configure this in the console at Workflows → [your workflow] → Face Match / Liveness → Duplicate detection.

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.

Upload an imported face to a User profile

If you are migrating from another KYC provider, you can create the User first and then attach a trusted face image to that profile. The User is still keyed by your vendor_data, but the face upload endpoint uses Didit’s internal User id (didit_internal_id) so the target is unambiguous.

Create or retrieve the User

Call POST /v3/users/create/ with your stable vendor_data, or call GET /v3/users/{vendor_data}/ if the User already exists.

Read didit_internal_id

The User response includes didit_internal_id. Keep using vendor_data in your own system; use didit_internal_id only for profile attachment endpoints.

Upload the face

Call

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

with a base64-encoded face image.

# 1. Create or retrieve the User keyed by your vendor_data
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# Response includes:
# { "didit_internal_id": "11111111-2222-3333-4444-555555555555", ... }

# 2. Upload the imported face to the User profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/11111111-2222-3333-4444-555555555555/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'

Imported profile faces are enrolled into the same face index used for duplicate detection and face search. They are not automatically blocklisted. To block a known bad actor, upload the face to a face-type list instead.

Only upload faces you are allowed to process under your own privacy notice and migration agreement. Keep source-provider identifiers in metadata or comment only when they are safe to expose to your compliance operators.

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.

Profile face upload and face blocklist upload are different operations. Use profile upload to attach a trusted imported face to a User for evidence, duplicate detection, and face search. Use the Lists API to block a face so future matching sessions are rejected.

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.
The face is enrolled for profile evidence, duplicate detection, and face search. Use the Blocklist area when the goal is to reject future matching sessions.

This is useful when:

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.

Overview

Pricing

Workflows & Verification

Review & Operations

Entities (Users & Businesses)

Settings & Customization

Security & Compliance

Resources

How faces attach to a user

Face search (1:N)

Duplicate detection

Face blocklist

Upload an imported face to a User profile

How blocklisting happens

Uploading a face to the blocklist

Removing a face from the blocklist

Face lifecycle summary

Upload a face from the console

Privacy and retention

Next steps

Face Search

Liveness

Blocklist API

User blocklist

​How faces attach to a user

​Face search (1:N)

​Duplicate detection

​Face blocklist

​Upload an imported face to a User profile

​How blocklisting happens

​Uploading a face to the blocklist

​Removing a face from the blocklist

​Face lifecycle summary

​Upload a face from the console

​Privacy and retention

​Next steps

Face Search

Liveness

Blocklist API

User blocklist

How faces attach to a user

Face search (1:N)

Duplicate detection

Face blocklist

Upload an imported face to a User profile

How blocklisting happens

Uploading a face to the blocklist

Removing a face from the blocklist

Face lifecycle summary

Upload a face from the console

Privacy and retention

Next steps