### 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** | — | Facial image (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 Manual Checks |
| `vendor_data` | string | No | — | Your identifier for session tracking |

### Example

### Status Values & Handling

| Status | Meaning | Action |
|---|---|---|
| `"Approved"` | Age verified above threshold, liveness passed | Proceed with your flow |
| `"Declined"` | Age below minimum or liveness failed | Check `warnings` for specifics |
| `"In Review"` | Borderline case, needs review | Trigger ID verification fallback or manual review |

### 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"`, `"Not Finished"` |
| `method` | string | `"ACTIVE_3D"`, `"FLASHING"`, or `"PASSIVE"` |
| `score` | float | 0-100 liveness confidence score |
| `age_estimation` | float | Estimated age in years (e.g. `24.3`). `null` if no face |
| `reference_image` | string | Temporary URL (expires 60 min) |
| `video_url` | string | Temporary URL for active liveness video. `null` for passive |
| `warnings` | array | `{risk, log_type, short_description, long_description}` |

### Accuracy by Age Range

| Age Range | MAE (years) | Confidence |
|---|---|---|
| Under 18 | 1.5 | High |
| 18-25 | 2.8 | High |
| 26-40 | 3.2 | High |
| 41-60 | 3.9 | Medium-High |
| 60+ | 4.5 | Medium |

---

## Warning Tags

### Auto-Decline

| Tag | Description |
|---|---|
| `NO_FACE_DETECTED` | No face found in image |
| `LIVENESS_FACE_ATTACK` | Spoofing attempt detected |
| `FACE_IN_BLOCKLIST` | Face matches a blocklist entry |

### Configurable (Decline / Review / Approve)

| Tag | Description |
|---|---|
| `AGE_BELOW_MINIMUM` | Estimated age below configured minimum |
| `AGE_NOT_DETECTED` | Unable to estimate age (image quality, lighting) |
| `LOW_LIVENESS_SCORE` | Liveness score below threshold |
| `POSSIBLE_DUPLICATED_FACE` | Significant similarity with previously verified face |

Warning severity: `error` (→ Declined), `warning` (→ In Review), `information` (no effect).

---

## Common Workflows

### Basic Age Gate

import requests

response = requests.post(
    "https://verification.didit.me/v3/age-estimation/",
    headers={"x-api-key": "YOUR_API_KEY"},
    files={"user_image": ("selfie.jpg", open("selfie.jpg", "rb"), "image/jpeg")},
    data={"vendor_data": "user-123"},
)
print(response.json())

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

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

{
  "request_id": "a1b2c3d4-...",
  "liveness": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 89.92,
    "age_estimation": 24.3,
    "reference_image": "https://example.com/reference.jpg",
    "video_url": null,
    "warnings": []
  },
  "created_at": "2025-05-01T13:11:07.977806Z"
}

1. Capture user selfie
2. POST /v3/age-estimation/ → {"user_image": selfie}
3. Check liveness.age_estimation >= your_minimum_age
4. If "Approved" → user meets age requirement
   If "Declined" → check warnings for AGE_BELOW_MINIMUM or liveness failure

1. Configure workflow with age thresholds in Console
2. POST /v3/session/ → create session with age-estimation workflow
3. User takes selfie → system estimates age
4. Clear pass (well above threshold) → Approved instantly
   Clear fail (well below threshold) → Declined
   Borderline case → automatic ID verification fallback
5. If ID fallback triggered: per-country age restrictions apply