OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add didit-protocol/skills --skill didit-face-search
Integrate Didit Face Search standalone API to perform 1:N facial search against all previously verified sessions. Use when the user wants to detect duplicate accounts, search for matching faces, check if a face already exists in the system, prevent duplicate registrations, search against blocklist, or implement facial deduplication using Didit. Returns ranked matches with similarity percentages.
npx skills add didit-protocol/skills --skill didit-face-search
Compares a reference face against all previously approved verification sessions to detect duplicate accounts and blocklisted faces. Returns ranked matches with similarity scores.
Key constraints:
Similarity score guidance:
| Range | Interpretation |
|---|---|
| 90%+ | Strong likelihood of same person |
| 70-89% | Possible match, may need manual review |
| Below 70% | Likely different individuals |
API Reference: https://docs.didit.me/standalone-apis/face-search Feature Guide: https://docs.didit.me/core-technology/face-search/overview
All requests require x-api-key header. Get your key from Didit Business Console → API & Webhooks, or via programmatic registration (see below).
If you don't have a Didit API key, create one in 2 API calls:
POST https://apx.didit.me/auth/v2/programmatic/register/ with {"email": "you@gmail.com", "password": "MyStr0ng!Pass"}POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with {"email": "you@gmail.com", "code": "A3K9F2"} → response includes api_keyTo add credits: GET /v3/billing/balance/ to check, POST /v3/billing/top-up/ with {"amount_in_dollars": 50} for a Stripe checkout link.
See the didit-verification-management skill for full platform management (workflows, sessions, users, billing).
| Header | Value | Required |
|---|---|---|
x-api-key | Your API key | Yes |
Content-Type | multipart/form-data | Yes |
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
user_image | file | Yes | — | Face image to search (JPEG/PNG/WebP/TIFF, max 5MB) |
rotate_image | boolean | No | false | Try 0/90/180/270 rotations for non-upright faces |
save_api_request | boolean | No | true | Save in Business Console |
vendor_data | string | No | — | Your identifier for session tracking |
| Status | Meaning | Action |
|---|---|---|
"Approved" | No concerning matches found | Proceed — new unique user |
"In Review" | Matches above similarity threshold | Review matches[] for potential duplicates |
"Declined" | Blocklist match or policy violation | Check matches[].is_blocklisted and warnings |
| Code | Meaning | Action |
|---|---|---|
400 | Invalid request | Check file format, size, parameters |
401 | Invalid API key | Verify x-api-key header |
403 | Insufficient credits | Top up at business.didit.me |
| Field | Type | Description |
|---|---|---|
session_id | string | UUID of the matching session |
session_number | integer | Session number |
similarity_percentage | float | 0-100 similarity score |
vendor_data | string | Your reference from the matching session |
verification_date | string | ISO 8601 timestamp |
user_details.name | string | Name from the matching session |
user_details.document_type | string | Document type used |
user_details.document_number | string | Partially masked document number |
match_image_url | string | Temporary URL (expires 4 hours) |
status | string | Status of the matching session |
is_blocklisted | boolean | Whether the match is from the blocklist |
| Field | Type | Description |
|---|---|---|
entities[].age | string | Estimated age |
entities[].bbox | array | Face bounding box [x1, y1, x2, y2] |
entities[].confidence | float | Detection confidence (0-1) |
entities[].gender | string | "male" or "female" |
best_angle | integer | Rotation applied (0, 90, 180, 270) |
| Tag | Description |
|---|---|
NO_FACE_DETECTED | No face found in image |
FACE_IN_BLOCKLIST | Face matches a blocklisted entry |
| Tag | Description |
|---|---|
MULTIPLE_FACES_DETECTED | Multiple faces detected — unclear which to use |
Similarity threshold and allow multiple faces settings are configurable in Console.
Warning severity: error (→ Declined), warning (→ In Review), information (no effect).
Security: Match image URLs expire after 4 hours. Store only
session_idandsimilarity_percentage— minimize biometric data on your servers.
search_faces.py: Search for matching faces from the command line.
const formData = new FormData();
formData.append("user_image", photoFile);
const response = await fetch("https://verification.didit.me/v3/face-search/", {
method: "POST",
headers: { "x-api-key": "YOUR_API_KEY" },
body: formData,
});{
"request_id": "a1b2c3d4-...",
"face_search": {
"status": "Approved",
"total_matches": 1,
"matches": [
{
"session_id": "uuid-...",
"session_number": 1234,
"similarity_percentage": 95.2,
"vendor_data": "user-456",
"verification_date": "2025-06-10T10:30:00Z",
"user_details": {
"name": "Elena Martinez",
"document_type": "Identity Card",
"document_number": "***456"
},
"match_image_url": "https://example.com/match.jpg",
"status": "Approved",
"is_blocklisted": false
}
],
"user_image": {
"entities": [
{"age": "27.6", "bbox": [40, 40, 120, 120], "confidence": 0.95, "gender": "female"}
],
"best_angle": 0
},
"warnings": []
}
}1. During new user registration
2. POST /v3/face-search/ → {"user_image": selfie}
3. If total_matches == 0 → new unique user
If matches found → check similarity_percentage:
90%+ → likely duplicate, investigate matches[].vendor_data
70-89% → possible match, flag for manual review1. POST /v3/passive-liveness/ → verify user is real
2. POST /v3/face-search/ → check for existing accounts
3. POST /v3/id-verification/ → verify identity document
4. POST /v3/face-match/ → compare selfie to document photo
5. All Approved → verified, unique, real user# Requires: pip install requests
export DIDIT_API_KEY="your_api_key"
python scripts/search_faces.py selfie.jpg
python scripts/search_faces.py photo.png --rotate --vendor-data user-123