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": "you@gmail.com", "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": "you@gmail.com", "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

python
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())

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

json
{
  "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.

bash
# 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