Skip to content
Back to skills

Didit Liveness Detection

ASecurity

Use when writing backend or API-key integration code for Didit's standalone passive liveness check on a single selfie image (POST /v3/passive-liveness/). Use when checking that a person is physically present, detecting spoofing or presentation attacks (printed photos, screen replays, masks, deepfakes), adding anti-spoofing to a selfie step, or screening a selfie against the face blocklist and earlier approved faces. Returns a 0-100 liveness score, an Approved/Declined status against a configu...

  • 28 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 18, 2026
ai-agentstypescriptpythonbashapibackendsecurity

Works with

  • cursor
  • cli
  • api
  • mcp

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned November 18, 2026

npx -y skills add didit-protocol/skills --skill didit-liveness-detection --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Didit Liveness Detection?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Didit Liveness Detection
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/didit-protocol-didit-liveness-detection/badge)](https://www.skillsdirectory.com/skills/didit-protocol-didit-liveness-detection)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: didit-liveness-detection
description: >
  Use when writing backend or API-key integration code for Didit's standalone passive liveness
  check on a single selfie image (POST /v3/passive-liveness/). Use when checking that a person
  is physically present, detecting spoofing or presentation attacks (printed photos, screen
  replays, masks, deepfakes), adding anti-spoofing to a selfie step, or screening a selfie
  against the face blocklist and earlier approved faces. Returns a 0-100 liveness score, an
  Approved/Declined status against a configurable decline threshold, face quality and luminance,
  and blocklist and duplicate-face warnings.
version: 1.4.0
metadata:
  openclaw:
    requires:
      env:
        - DIDIT_API_KEY
    primaryEnv: DIDIT_API_KEY
    emoji: "🧑"
    homepage: https://docs.didit.me
---

# Didit Passive Liveness API

> Working inside a connected Didit account (Claude, ChatGPT, Cursor)? Use the Didit plugin or the Didit MCP server tools instead of these REST calls.

## Overview

Verifies that a user is physically present by analyzing a single captured image. No video, movement or user interaction is required.

**Key constraints:**
- Allowed file extensions: **tiff, jpg, jpeg, png, webp** (no PDF)
- Maximum file size: **5 MB** (images are compressed to about 0.5 MB before processing, so higher resolutions do not improve accuracy)
- One clearly visible face. With several faces the largest one is scored and `MULTIPLE_FACES_DETECTED` is added
- Original real-time capture (no screenshots, prints or photos of screens)

**Pricing (list prices as of 2026-11-18, [pricing](https://docs.didit.me/getting-started/pricing)):** $0.05 per successful standalone call, paid from your plan credit or top-ups. Current prices: [didit.me/pricing](https://didit.me/pricing). Billing statements elsewhere in this skill (what is or is not billed) refer to this note and its date.

**Accuracy:** 99.9% liveness detection accuracy, <0.1% false acceptance rate (FAR).

**Decision:** `status` is `Declined` when any `error` warning fires (no face, score at or below the threshold, presentation attack, blocklist hit) and `Approved` otherwise. There is no `In Review` on this endpoint. Only the score threshold is configurable.

**Blocklist and duplicate screening:** runs on **every** call, also with `save_api_request=false`. The face is compared with your application's face search index (your face blocklist and allowlist, faces from approved sessions, faces uploaded to User profiles and retained biometric templates). Earlier faces with the same `vendor_data` are skipped for the duplicate check, so re-verifying the same user does not raise `DUPLICATED_FACE`. A blocklisted face is still caught when it carries the same `vendor_data`. A match on your face allowlist suppresses the duplicate warnings.

**Saving and enrollment (`save_api_request`, default `true`):** the call is saved as an API session (Business Console, `GET /v3/session/{request_id}/decision/`, `status.updated` webhook), the image and face crop are stored, and the face is **enrolled into your face search index** so later Face Search calls and duplicate checks can match it. With `false` nothing is stored, the face is not enrolled and `request_id` cannot be looked up.

**Sandbox:** sandbox API keys return a static `Approved` payload after request validation; nothing is saved or billed (see Pricing above).

**Liveness methods:** this endpoint always uses `PASSIVE` (single-frame CNN). Hosted workflows can also use `ACTIVE_3D` (3D Action & Flash, highest security) and `FLASHING` (3D Flash, high security) through the `face_liveness_method` workflow setting.

**API Reference:** https://docs.didit.me/standalone-apis/passive-liveness
**Feature Guide:** https://docs.didit.me/core-technology/liveness/overview

---

## Authentication

Every request needs the `x-api-key` header. Use your application's API key from the [Didit Business Console](https://business.didit.me) under **Developers > API keys**, or create an account and key programmatically (see Getting Started). Named keys with custom access need **Sessions** write to run standalone checks; a key limited to some workflows or to approved sessions cannot run them.

## 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@yourdomain.com", "password": "<your-password>"}`
2. **Check email** for a 6-character verification code
3. **Verify:** `POST https://apx.didit.me/auth/v2/programmatic/verify-email/` with `{"email": "you@yourdomain.com", "code": "A3K9F2"}`. The key is in the response at `application.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. Before calling it, confirm the amount with the person: the checkout link charges them that amount.

See the **didit-verification-management** skill for full platform management (workflows, sessions, users, billing).

---

## Endpoint

```
POST https://verification.didit.me/v3/passive-liveness/
```

### Headers

| Header | Value | Required |
|---|---|---|
| `x-api-key` | Your API key | **Yes** |
| `Content-Type` | `multipart/form-data` (set by your HTTP client) | **Yes** |

### Request Parameters (multipart/form-data)

| Parameter | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `user_image` | file | **Yes** | - | tiff/jpg/jpeg/png/webp, max 5 MB | Front-facing face image (selfie) |
| `face_liveness_score_decline_threshold` | float | No | `30` | 0-100 | A score **at or below** this value raises `LOW_LIVENESS_SCORE` and declines. Raise it for a stricter anti-spoofing posture |
| `rotate_image` | boolean | No | `false` | - | Try 90-degree rotations and use the orientation with the best face detection. Adds latency |
| `save_api_request` | boolean | No | `true` | - | Save as an API session and enroll the face (see Overview) |
| `vendor_data` | string | No | - | - | Your user identifier. Stored, echoed back, and used to skip the same user's earlier faces in the duplicate check |
| `metadata` | JSON object | No | - | JSON-encoded string in multipart | Stored with the session (when saved) and echoed back |

### Example

```python
import json

import requests

with open("selfie.jpg", "rb") as f:
    response = requests.post(
        "https://verification.didit.me/v3/passive-liveness/",
        headers={"x-api-key": "YOUR_API_KEY"},
        files={"user_image": ("selfie.jpg", f, "image/jpeg")},
        data={
            "face_liveness_score_decline_threshold": "50",
            "vendor_data": "user-123",
            "metadata": json.dumps({"flow": "withdrawal"}),
        },
        timeout=60,
    )
response.raise_for_status()
liveness = response.json()["liveness"]
print(liveness["status"], liveness["score"], [w["risk"] for w in liveness["warnings"]])
```

```typescript
const formData = new FormData();
formData.append("user_image", selfieFile);
formData.append("face_liveness_score_decline_threshold", "50");
formData.append("vendor_data", "user-123");
formData.append("metadata", JSON.stringify({ flow: "withdrawal" }));

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

### Response (200 OK)

```json
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "liveness": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 95.0,
    "user_image": {
      "entities": [
        {"bbox": [661, 728, 1688, 2188], "confidence": 0.732973, "age": 26.91, "gender": "male"}
      ],
      "best_angle": 0
    },
    "warnings": [],
    "face_quality": 84.21,
    "face_luminance": 50.33
  },
  "vendor_data": "user-123",
  "metadata": {"flow": "withdrawal"},
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

A spoofed or blocklisted face still returns HTTP `200`: always read `liveness.status` and `liveness.warnings`.

### Status Values & Handling

| Status | Meaning | Action |
|---|---|---|
| `"Approved"` | No `error` warning fired | Proceed. Still check `warnings` for `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` / `MULTIPLE_FACES_DETECTED` |
| `"Declined"` | At least one `error` warning fired | Read `warnings[].risk`: retake for capture problems, block or review for attacks and blocklist hits |

### Error Responses

| Code | Meaning | Action |
|---|---|---|
| `400` | Invalid request | Read the field errors in the response body |
| `400` | `{"error": "Invalid user image format."}`: allowed extension but the file cannot be decoded | Re-encode the image (JPEG or PNG) and retry |
| `401` | The API key has expired | Rotate it or create a new key in **Developers > API keys** |
| `403` | Missing, wrong or revoked API key; a scoped key without access to this endpoint; a request from outside the key's IP allowlist; or not enough credits | Read the message in `detail` or `error`: fix the `x-api-key` header or the key's access, or top up |
| `429` | Rate limit: 300 POST/PATCH/DELETE and 600 GET requests a minute per key | Wait the `Retry-After` seconds, then retry |

---

## Response Field Reference

| Field | Type | Description |
|---|---|---|
| `request_id` | uuid | Session id when `save_api_request=true` (use with `GET /v3/session/{request_id}/decision/`); otherwise a one-off correlation id |
| `liveness.status` | string | `"Approved"` or `"Declined"` |
| `liveness.method` | string | Always `"PASSIVE"` |
| `liveness.score` | float or null | 0-100 (two decimals), higher means more likely a live person. `null` when the model returned no confidence; a `null` score counts as 0 against the threshold |
| `liveness.user_image.entities[]` | array | One entry per detected face: `bbox` `[x_min, y_min, x_max, y_max]`, `confidence` (0-1), `age`, `gender`. Age and gender are informational and do not affect the decision |
| `liveness.user_image.best_angle` | integer or null | Rotation (degrees) that gave the best detection; non-zero only when `rotate_image=true` corrected it |
| `liveness.warnings[]` | array | `{risk, feature, additional_data, log_type, short_description, long_description}`. `feature` is always `LIVENESS` |
| `liveness.face_quality` | float or null | Capture quality of the face, 0-100. `null` when no reliable value |
| `liveness.face_luminance` | float or null | Brightness of the face, 0-100. `null` when unavailable |
| `vendor_data` | string or null | Echo of what you sent |
| `metadata` | object or null | Echo of what you sent |
| `created_at` | string | ISO 8601 UTC time of the response |

---

## Warning Tags

| Tag | Severity | Declines | When it fires |
|---|---|---|---|
| `NO_FACE_DETECTED` | `error` | Yes | The liveness model found no face |
| `LOW_LIVENESS_SCORE` | `error` | Yes | `score` at or below `face_liveness_score_decline_threshold`. Not raised together with `NO_FACE_DETECTED` |
| `LIVENESS_FACE_ATTACK` | `error` | Yes | Presentation attack detected (print, screen replay, mask, deepfake) |
| `FACE_IN_BLOCKLIST` | `error` | Yes | Strong match with a face on your face blocklist. `additional_data` includes `blocklisted_session_id`, `blocklisted_session_number`, `api_service` |
| `POSSIBLE_FACE_IN_BLOCKLIST` | `error` | Yes | Weaker match with a blocklisted face. This endpoint declines it (workflows send it to review) |
| `MULTIPLE_FACES_DETECTED` | `warning` | No | More than one face; the largest one was scored |
| `DUPLICATED_FACE` | `information` | No | Strong match with a face from another approved session (or an imported face or retained template). `additional_data` includes `duplicated_session_id`, `duplicated_session_number`, `api_service` |
| `POSSIBLE_DUPLICATED_FACE` | `information` | No | Weaker match of the same kind |

- `LOW_FACE_QUALITY`, `LOW_FACE_LUMINANCE` and `HIGH_FACE_LUMINANCE` are **never** raised by this endpoint (they are workflow warnings). Apply your own rule to `face_quality` / `face_luminance` if you need one.
- Base decisions on `status` and `warnings[].risk`. The severities above are this endpoint's rules; treat the `log_type` echoed on each warning as informational.

---

## Common Workflows

### Basic Liveness Check

```
1. Capture the user's selfie
2. POST /v3/passive-liveness/ with user_image and vendor_data=<your user id>
3. "Approved" -> the user is live, proceed
   "Declined" -> check warnings[].risk:
     NO_FACE_DETECTED / LOW_LIVENESS_SCORE -> ask for a retake: one well-lit, centered face
     LIVENESS_FACE_ATTACK                  -> suspected spoof, do not approve
     FACE_IN_BLOCKLIST / POSSIBLE_FACE_IN_BLOCKLIST -> block or send to manual review
4. "Approved" with DUPLICATED_FACE -> this face already passed under another vendor_data:
   look up additional_data.duplicated_session_id before creating a new account
```

### Liveness + Face Match (combined)

```
1. POST /v3/passive-liveness/ -> verify the selfie is live
2. If Approved -> POST /v3/face-match/ with user_image=selfie, ref_image=ID portrait
3. Both Approved -> the live person matches the document photo
```

Need a ranked list of every similar face rather than a blocklist/duplicate verdict? Use the **didit-face-search** skill, and run it before saving the same selfie here (a saved liveness face is itself searchable).

---

## Utility Scripts

```bash
export DIDIT_API_KEY="your_api_key"

python scripts/check_liveness.py selfie.jpg
python scripts/check_liveness.py selfie.jpg --threshold 50 --vendor-data user-123
python scripts/check_liveness.py selfie.jpg --rotate --no-save --metadata '{"flow": "withdrawal"}'
```

Files in this skill

  • SKILL.md13.3 KB
  • scripts/check_liveness.py3.7 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.