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

Security Scan

The skill's requests, instructions, and included script consistently match its stated purpose (calling Didit Face Search with a DIDIT_API_KEY); nothing in the bundle appears disproportionate or unrelated.

Purpose & Capability

Name/description match the required credential (DIDIT_API_KEY), endpoint URLs, and the included Python script. No unrelated environment variables or binaries are requested.

Instruction Scope

SKILL.md and the script instruct the agent to POST an image to Didit's face-search endpoint using the API key. The instructions do not ask the agent to read unrelated files, other env vars, or to transmit data to unexpected endpoints. (Note: the skill inherently handles sensitive biometric data — expected for the stated purpose.)

Install Mechanism

There is no install spec (instruction-only skill) and included code is a small helper script. Nothing is downloaded or installed from untrusted URLs.

Credentials

Only DIDIT_API_KEY is required and declared as the primary credential, which is appropriate for calling the Didit API. No unrelated secrets or config paths are requested.

Persistence & Privilege

always is false and the skill does not request persistent system privileges or modify other skills. Autonomous invocation is allowed (default) but not combined with any other concerning capabilities.

Assessment

This skill legitimately calls Didit's face-search API and requires your DIDIT_API_KEY. Before installing, be aware: the skill will send user images (biometric data) to didit.me — ensure you have consent and that this complies with your privacy/legal requirements. Store the DIDIT_API_KEY securely and limit its permissions if possible. The included script is small and consistent with the docs, but review it for minor issues (e.g., the script prints a 'similarity' field that may not match the API's 'similarity_percentage' naming). Verify the publisher/owner if you need provenance, and test with non-sensitive images first.

Didit Face Search API (1:N)

Overview

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:

• Supported formats: JPEG, PNG, WebP, TIFF
• Maximum file size: 5MB
• Compares against all approved sessions in your application
• Blocklist matches cause automatic decline

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

---

Authentication

All requests require x-api-key header. Get your key from Didit Business Console → API & Webhooks, or via programmatic registration (see below).

Getting Started (No Account Yet?)

If you don't have a Didit API key, create one in 2 API calls:

1. Register: POST https://apx.didit.me/auth/v2/programmatic/register/ with {"email": "[e-mail]", "password": "MyStr0ng!Pass"}
2. Check email for a 6-character OTP code
3. Verify: POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with {"email": "[e-mail]", "code": "A3K9F2"} → response includes api_key

To 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).

---

Endpoint

POST https://verification.didit.me/v3/face-search/

Headers

Header	Value	Required
x-api-key	Your API key	Yes
Content-Type	multipart/form-data	Yes

Request Parameters (multipart/form-data)

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

Example

import requests

response = requests.post(
    "https://verification.didit.me/v3/face-search/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={"user_image": ("photo.jpg", open("photo.jpg", "rb"), "image/jpeg")},
)
print(response.json())

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,
});

Response (200 OK)

{
  "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": []
  }
}

Status Values & Handling

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

Error Responses

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

---

Response Field Reference

Match Object

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 60 min)
status	string	Status of the matching session
is_blocklisted	boolean	Whether the match is from the blocklist

User Image Object

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)

---

Warning Tags

Auto-Decline

Tag	Description
NO_FACE_DETECTED	No face found in image
FACE_IN_BLOCKLIST	Face matches a blocklisted entry

Configurable

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

---

Common Workflows

Duplicate Account Detection

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 review

Combined Verification + Dedup

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

Security: Match image URLs expire after 60 minutes. Store only session_id and similarity_percentage — minimize biometric data on your servers.

---

Utility Scripts

search_faces.py: Search for matching faces from the command line.

# 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