Faces and Biometrics

​

How faces attach to a user

​

Face search (1:N)

• 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

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

​

Face blocklist

​

Upload an imported face to a User profile

# 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"
  }'

​

How blocklisting happens

​

Uploading a face to the blocklist

​

Removing a face from the blocklist

​

Retained biometric templates after session deletion

• It contains the numeric face template plus retention metadata only. It never contains the face image, liveness video, document data, extracted identity fields, the decision, or the deleted session’s id.
• It takes part in duplicate detection, Face Search, biometric authentication, and your face lists exactly like a live session face. Hits are reported with source: "retained_template", the User’s vendor_user_id and vendor_data, and a biometric_template_id.
• It is biometric data with a finite expires_at. It is purged when the User is deleted, when any session of that User is deleted with deletion_instruction: "privacy_erasure", when it expires, or when you purge it in Lists → Biometric templates or through the Biometric Templates API.
• A session created without vendor_data has no User to anchor a template to; deleting it reports ineligible_no_vendor_user and the embedding is deleted with the session.
• Retained templates are never blocklisted. A face blocklist entry created from the deleted session keeps its own independent biometric entry and lifecycle.

​

Face lifecycle summary

​

Upload a face from the console

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.

• 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. A face embedding is biometric data.
• Retention follows your application’s data retention policy. Retained biometric templates follow the stricter, finite biometric-template retention period.
• Deleting a session deletes the image and, by default, the embedding. If your application has opted in to biometric-template retention, deleting a session keeps an image-free template until it expires or is purged.
• For a GDPR / CCPA right-to-be-forgotten request, delete the person’s sessions with deletion_instruction: "privacy_erasure" or delete the User: both purge every retained template as well. Face blocklist entries you manage stay until you remove them.

​

Next steps