### 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 |
| `face_liveness_score_decline_threshold` | integer | No | — | 0-100 | Scores below this = Declined |
| `rotate_image` | boolean | No | — | — | Try rotations to find upright face |
| `save_api_request` | boolean | No | `true` | — | Save in Business Console |
| `vendor_data` | string | No | — | — | Your identifier for session tracking |

### Example

### Status Values & Handling

| Status | Meaning | Action |
|---|---|---|
| `"Approved"` | User is physically present | Proceed with your flow |
| `"Declined"` | Liveness check failed | Check `warnings`. May be a spoof or poor image quality |

### 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"` or `"Declined"` |
| `method` | string | Always `"PASSIVE"` for this endpoint |
| `score` | integer | 0-100 liveness confidence (higher = more likely real). `null` if no face |
| `face_quality` | float | 0-100 face image quality score. `null` if no face |
| `face_luminance` | float | Face luminance value. `null` if no face |
| `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"` |
| `warnings` | array | `{risk, log_type, short_description, long_description}` |

---

## Warning Tags

### Auto-Decline (always)

| Tag | Description |
|---|---|
| `NO_FACE_DETECTED` | No face detected in image |
| `LIVENESS_FACE_ATTACK` | Potential spoofing attempt (printed photo, screen, mask) |
| `FACE_IN_BLOCKLIST` | Face matches a blocklisted entry |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Possible blocklist match detected |

### Configurable (Decline / Review / Approve)

| Tag | Description | Notes |
|---|---|---|
| `LOW_LIVENESS_SCORE` | Score below threshold | Configurable review + decline thresholds |
| `DUPLICATED_FACE` | Matches another approved session | — |
| `POSSIBLE_DUPLICATED_FACE` | May match another user | Configurable similarity threshold |
| `MULTIPLE_FACES_DETECTED` | Multiple faces (largest used for scoring) | Passive only |
| `LOW_FACE_QUALITY` | Image quality below threshold | Passive only |
| `LOW_FACE_LUMINANCE` | Image too dark | Passive only |
| `HIGH_FACE_LUMINANCE` | Image too bright/overexposed | Passive only |

---

## Common Workflows

### Basic Liveness Check

---

## Utility Scripts

import requests

response = requests.post(
    "https://verification.didit.me/v3/passive-liveness/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={"user_image": ("selfie.jpg", open("selfie.jpg", "rb"), "image/jpeg")},
    data={"face_liveness_score_decline_threshold": "80"},
)

const formData = new FormData();
formData.append("user_image", selfieFile);
formData.append("face_liveness_score_decline_threshold", "80");

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

{
  "request_id": "a1b2c3d4-...",
  "liveness": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 95,
    "user_image": {
      "entities": [
        {"age": 22.16, "bbox": [156, 234, 679, 898], "confidence": 0.717, "gender": "male"}
      ],
      "best_angle": 0
    },
    "warnings": [],
    "face_quality": 85.0,
    "face_luminance": 50.0
  },
  "created_at": "2025-05-01T13:11:07.977806Z"
}

1. Capture user selfie
2. POST /v3/passive-liveness/ → {"user_image": selfie}
3. If "Approved" → user is real, proceed
   If "Declined" → check warnings:
     - NO_FACE_DETECTED → ask user to retake with face clearly visible
     - LOW_FACE_QUALITY → ask for better lighting/positioning
     - LIVENESS_FACE_ATTACK → flag as potential fraud

1. POST /v3/passive-liveness/ → verify user is real
2. If Approved → POST /v3/face-match/ → compare selfie to ID photo
3. Both Approved → identity verified

export DIDIT_API_KEY="your_api_key"

python scripts/check_liveness.py selfie.jpg
python scripts/check_liveness.py selfie.jpg --threshold 80