Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.didit.me/llms.txt

Use this file to discover all available pages before exploring further.

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

​
How faces attach to a user

1

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.
2

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.
3

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:

​
Duplicate detection

Every new face can be compared against existing enrolled faces to surface duplicates. Didit assigns each face an approved_duplicate_status:
StatusMeaning
NOT_DUPLICATEDNo matches found above the similarity threshold
DUPLICATEDFace 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.
1

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.
2

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.
3

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

TriggerAction
Session DECLINED and auto-blocklist enabledFace added to the system face list, user status → BLOCKED
Analyst manually blocklists a face from the consoleFace added, user status updated per policy
Programmatic add via the Lists APIUpload 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:
  1. Navigate to Users → [user] → Actions → Upload face.
  2. Select an image; Didit extracts the largest face and stores a new Face record linked to the user.
  3. 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.