Didit Age Estimation API

Overview

Estimates a person's age from a facial image using deep learning. Also performs a passive liveness check to prevent spoofing.

Key constraints:

•Supported formats: JPEG, PNG, WebP, TIFF
•Maximum file size: 5MB
•Image must contain one clearly visible face
•Accuracy: MAE ±3.5 years overall; ±1.5 years for under-18

Capabilities: Age estimation with confidence scoring, gender estimation, passive liveness detection, configurable age thresholds, per-country age restrictions, adaptive mode with ID verification fallback for borderline cases.

Liveness methods (workflow mode):

Method	Security	Best For
`ACTIVE_3D` (Action + Flash)	Highest	Banking, government, healthcare
`FLASHING` (3D Flash)	High	Financial services, identity verification
`PASSIVE` (single-frame CNN)	Standard	Low-friction consumer apps

API Reference: https://docs.didit.me/reference/age-estimation-standalone-api

Authentication

All requests require x-api-key header. Get your key from Didit Business Console → API & Webhooks.

Endpoint

code

POST https://verification.didit.me/v3/age-estimation/

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

python

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

typescript

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,
});

Response (200 OK)

json

{
  "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"
}

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

code

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

Adaptive Age Estimation (Workflow Mode)

code

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

Per-Country Age Restrictions

Configure in Console per issuing country:

Country	Min Age	Overrides
USA	18	Mississippi: 21, Alabama: 19
KOR	19	—
GBR	18	—
ARE	21	—

Use "Apply age of majority" button in Console to auto-populate defaults.