✓ Verified 💻 Development ✓ Enhanced Data

Didit Face Match

Integrate Didit Face Match standalone API to compare two facial images.

Rating
3.9 (127 reviews)
Downloads
34,388 downloads
Version
1.0.0

Overview

Integrate Didit Face Match standalone API to compare two facial images.

Complete Documentation

View Source →

Didit Face Match API

Overview

Compares two facial images to determine if they belong to the same person. Returns a similarity score (0-100).

Key constraints:

  • Supported formats: JPEG, PNG, WebP, TIFF
  • Maximum file size: 5MB per image
  • If multiple faces in an image, the largest face is used for comparison
  • Both user_image and ref_image are required
Capabilities: Similarity scoring, age estimation, gender detection, face bounding boxes, configurable decline threshold, optional image rotation for non-upright faces.

API Reference: https://docs.didit.me/standalone-apis/face-match Feature Guide: https://docs.didit.me/core-technology/face-match/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:

  • Register: POST https://apx.didit.me/auth/v2/programmatic/register/ with {"email": "[email protected]", "password": "MyStr0ng!Pass"}
  • Check email for a 6-character OTP code
  • Verify: POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with {"email": "[email protected]", "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

text
POST https://verification.didit.me/v3/face-match/

Headers

HeaderValueRequired
x-api-keyYour API keyYes
Content-Typemultipart/form-dataYes

Request Parameters (multipart/form-data)

ParameterTypeRequiredDefaultConstraintsDescription
user_imagefileYes—JPEG/PNG/WebP/TIFF, max 5MBUser's face image to verify
ref_imagefileYes—Same as aboveReference image to compare against
face_match_score_decline_thresholdintegerNo300-100Scores below this = Declined
rotate_imagebooleanNofalse—Try 0/90/180/270 degree rotations to find upright face
save_api_requestbooleanNotrue—Save in Business Console Manual Checks
vendor_datastringNo——Your identifier for session tracking

Example

python
import requests

response = requests.post(
    "https://verification.didit.me/v3/face-match/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={
        "user_image": ("selfie.jpg", open("selfie.jpg", "rb"), "image/jpeg"),
        "ref_image": ("id_photo.jpg", open("id_photo.jpg", "rb"), "image/jpeg"),
    },
    data={"face_match_score_decline_threshold": "50"},
)

typescript
const formData = new FormData();
formData.append("user_image", selfieFile);
formData.append("ref_image", referenceFile);
formData.append("face_match_score_decline_threshold", "50");

const response = await fetch("https://verification.didit.me/v3/face-match/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: formData,
});

Response (200 OK)

json
{
  "request_id": "a1b2c3d4-...",
  "face_match": {
    "status": "Approved",
    "score": 80,
    "user_image": {
      "entities": [
        {"age": 27.63, "bbox": [40, 40, 100, 100], "confidence": 0.717, "gender": "male"}
      ],
      "best_angle": 0
    },
    "ref_image": {
      "entities": [
        {"age": 22.16, "bbox": [156, 234, 679, 898], "confidence": 0.717, "gender": "male"}
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "created_at": "2025-05-01T13:11:07.977806Z"
}

Status Values & Handling

StatusMeaningAction
"Approved"Score >= thresholdFaces match — proceed
"Declined"Score < threshold or no faceCheck warnings for details. May need better image
"In Review"Needs manual reviewWait for review or retrieve via session API

Error Responses

CodeMeaningAction
400Invalid requestCheck file format, size, parameters
401Invalid API keyVerify x-api-key header
403Insufficient creditsTop up at business.didit.me

Response Field Reference

FieldTypeDescription
statusstring"Approved", "Declined", "In Review"
scoreinteger0-100 similarity score (higher = more similar). null if no face found
entities[].agefloatEstimated age
entities[].bboxarrayFace bounding box [x1, y1, x2, y2]
entities[].confidencefloatFace detection confidence (0-1)
entities[].genderstring"male" or "female"
best_angleintegerBest rotation angle for the face
warningsarray{risk, log_type, short_description, long_description}

Warning Tags

TagDescriptionAuto-Decline
NO_REFERENCE_IMAGEReference or face image missingYes
NO_FACE_DETECTEDNo face detected in one or both imagesYes
LOW_FACE_MATCH_SIMILARITYScore below threshold — potential identity mismatchConfigurable
Security best practice: Only store the status and score. Minimize biometric image data on your servers. Image URLs (in workflow mode) expire after 60 minutes.

Score Interpretation

Score RangeInterpretationAction
90-100Very high confidence — same personAuto-approve
70-89High confidence — likely same personApprove (default threshold 30)
50-69Moderate — possible matchConsider manual review
30-49Low — likely different peopleDeclined at default threshold
0-29Very low — different peopleDeclined

Utility Scripts

bash
export DIDIT_API_KEY="your_api_key"

python scripts/match_faces.py selfie.jpg id_photo.jpg
python scripts/match_faces.py selfie.jpg id_photo.jpg --threshold 50 --rotate

Installation

Terminal bash 

openclaw install didit-face-match
Copied!

💻Code Examples

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

post-httpsverificationdiditmev3face-match.txt
### 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 | Constraints | Description |
|---|---|---|---|---|---|
| `user_image` | file | **Yes** | — | JPEG/PNG/WebP/TIFF, max 5MB | User's face image to verify |
| `ref_image` | file | **Yes** | — | Same as above | Reference image to compare against |
| `face_match_score_decline_threshold` | integer | No | `30` | 0-100 | Scores below this = Declined |
| `rotate_image` | boolean | No | `false` | — | Try 0/90/180/270 degree rotations to find upright face |
| `save_api_request` | boolean | No | `true` | — | Save in Business Console Manual Checks |
| `vendor_data` | string | No | — | — | Your identifier for session tracking |

### Example

}

.txt
### Status Values & Handling

| Status | Meaning | Action |
|---|---|---|
| `"Approved"` | Score >= threshold | Faces match — proceed |
| `"Declined"` | Score < threshold or no face | Check `warnings` for details. May need better image |
| `"In Review"` | Needs manual review | Wait for review or retrieve via session API |

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

| Field | Type | Description |
|---|---|---|
| `status` | string | `"Approved"`, `"Declined"`, `"In Review"` |
| `score` | integer | 0-100 similarity score (higher = more similar). `null` if no face found |
| `entities[].age` | float | Estimated age |
| `entities[].bbox` | array | Face bounding box `[x1, y1, x2, y2]` |
| `entities[].confidence` | float | Face detection confidence (0-1) |
| `entities[].gender` | string | `"male"` or `"female"` |
| `best_angle` | integer | Best rotation angle for the face |
| `warnings` | array | `{risk, log_type, short_description, long_description}` |

---

## Warning Tags

| Tag | Description | Auto-Decline |
|---|---|---|
| `NO_REFERENCE_IMAGE` | Reference or face image missing | Yes |
| `NO_FACE_DETECTED` | No face detected in one or both images | Yes |
| `LOW_FACE_MATCH_SIMILARITY` | Score below threshold — potential identity mismatch | Configurable |

> **Security best practice:** Only store the status and score. Minimize biometric image data on your servers. Image URLs (in workflow mode) expire after 60 minutes.

---

## Score Interpretation

| Score Range | Interpretation | Action |
|---|---|---|
| 90-100 | Very high confidence — same person | Auto-approve |
| 70-89 | High confidence — likely same person | Approve (default threshold 30) |
| 50-69 | Moderate — possible match | Consider manual review |
| 30-49 | Low — likely different people | Declined at default threshold |
| 0-29 | Very low — different people | Declined |

---

## Utility Scripts
example.py
import requests

response = requests.post(
    "https://verification.didit.me/v3/face-match/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={
        "user_image": ("selfie.jpg", open("selfie.jpg", "rb"), "image/jpeg"),
        "ref_image": ("id_photo.jpg", open("id_photo.jpg", "rb"), "image/jpeg"),
    },
    data={"face_match_score_decline_threshold": "50"},
)
example.ts
const formData = new FormData();
formData.append("user_image", selfieFile);
formData.append("ref_image", referenceFile);
formData.append("face_match_score_decline_threshold", "50");

const response = await fetch("https://verification.didit.me/v3/face-match/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: formData,
});
example.json
{
  "request_id": "a1b2c3d4-...",
  "face_match": {
    "status": "Approved",
    "score": 80,
    "user_image": {
      "entities": [
        {"age": 27.63, "bbox": [40, 40, 100, 100], "confidence": 0.717, "gender": "male"}
      ],
      "best_angle": 0
    },
    "ref_image": {
      "entities": [
        {"age": 22.16, "bbox": [156, 234, 679, 898], "confidence": 0.717, "gender": "male"}
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "created_at": "2025-05-01T13:11:07.977806Z"
}
example.sh
export DIDIT_API_KEY="your_api_key"

python scripts/match_faces.py selfie.jpg id_photo.jpg
python scripts/match_faces.py selfie.jpg id_photo.jpg --threshold 50 --rotate

Tags

#coding_agents-and-ides #api

Quick Info

Category Development
Model Claude 3.5
Complexity One-Click
Author rosasalberto
Last Updated 3/10/2026
🚀
Optimized for
Claude 3.5
🧠

Ready to Install?

Get started with this skill in seconds

openclaw install didit-face-match

Resources

📂
OpenClaw Skills
View on OpenClaw GitHub
→

Related Skills

✓ Verified 💻 Development

4claw

4claw — a moderated imageboard for AI agents.

🧠 Claude-Ready #ai_and-llms
)}
★ 4.4 (118)
↓ 4,990
v1.0.0
✓ Verified 💻 Development

Aap Passport

Agent Attestation Protocol - The Reverse Turing Test.

🧠 Claude-Ready #ai_and-llms
)}
★ 4.3 (89)
↓ 4,621
v1.0.0
✓ Verified 💻 Development

Acestep Lyrics Transcription

Transcribe audio to timestamped lyrics using OpenAI Whisper or ElevenLabs Scribe API.

⚡ GPT-Optimized #ai_and-llms #api #script
)}
★ 3.8 (274)
↓ 17,648
v1.0.0
✓ Verified 💻 Development

Adaptive Suite

A continuously adaptive skill suite that empowers Clawdbot.

🧠 Claude-Ready #ai_and-llms #bot
)}
★ 4.7 (88)
↓ 1,625
v1.0.0