Skip to main content
POST
/
v3
/
age-estimation
/
cURL
curl -X POST 'https://verification.didit.me/v3/age-estimation/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'user_image=@./selfie.jpg' \
  -F 'age_estimation_decline_threshold=18' \
  -F 'face_liveness_score_decline_threshold=30' \
  -F 'save_api_request=true' \
  -F 'vendor_data=user-123'
{
  "request_id": "0c40ba43-64ab-4e2e-b4b8-7d1f12f81bc1",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 97.5,
    "user_image": {
      "entities": [
        {
          "age": 27.33,
          "bbox": [
            40,
            40,
            100,
            100
          ],
          "confidence": 0.7177750468254089,
          "gender": "male"
        }
      ],
      "best_angle": 0
    },
    "age_estimation": 27.33,
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": {
    "flow": "age-gate"
  },
  "created_at": "2026-06-12T02:24:11.512941+00:00"
}

Authorizations

​
x-api-key
string
header
required

Body

multipart/form-data
​
user_image
file
required

Face photo to analyze (e.g. a selfie). Submit a single front-facing photo with the subject's face clearly visible and well lit. Allowed extensions: tiff, jpg, jpeg, png, webp (no PDF). Maximum upload size: 5 MB (larger files are rejected with 400). Images are automatically compressed to ~0.3 MB before processing, so very high resolutions do not improve accuracy.

​
face_liveness_score_decline_threshold
number<float>
default:30

Liveness threshold (0–100). A liveness score at or below this value adds a LOW_LIVENESS_SCORE warning and declines. Raise it for stricter anti-spoofing; values outside 0–100 return 400.

Required range: 0 <= x <= 100
Example:

30

​
age_estimation_decline_threshold
integer
default:18

Minimum acceptable estimated age in years. An estimated age below this value adds an AGE_BELOW_MINIMUM warning and declines. Set 0 to disable the age check (the call then only runs liveness + age estimation without an age-based decision).

Required range: 0 <= x <= 100
Example:

18

​
rotate_image
boolean
default:false

When true, the service tries the input image in 90-degree increments (0, 90, 180, 270) and uses the orientation that yields the best face detection — useful for mobile captures with missing EXIF orientation. Adds latency, so only enable it if you cannot guarantee upright images.

Example:

false

​
save_api_request
boolean
default:true

When true (default), persists the call as an API-type session — visible in the Business Console, retrievable via GET /v3/session/{sessionId}/decision/ using the returned request_id, announced through a status.updated webhook, and with the detected face added to your application's face index. When false, nothing is stored and request_id is a transient UUID for response correlation only.

Example:

true

​
vendor_data
string

Optional opaque string (your internal user id, email, UUID…) stored on the persisted session and echoed back in the response. Use it to correlate API calls with your own records and to filter sessions later.

Example:

"user-123"

​
metadata
object

Optional JSON object stored with the session (when save_api_request=true) and echoed back in the response. In multipart requests, send it as a JSON-encoded string field (e.g. metadata={"flow":"age-gate"}) — it is parsed into an object.

Example:
{ "flow": "age-gate" }

Response

Age estimation and passive liveness completed. age_estimation.age_estimation is the model-predicted age in years of the largest detected face (null if none); age_estimation.score is the passive-liveness score (0–100); status is Approved only when warnings is empty. An underage or spoofed capture still returns 200 with status: "Declined" — inspect the body, not just the HTTP code. When save_api_request=true, request_id is the persisted session id.

​
request_id
string<uuid>

Persisted session id when save_api_request=true (usable with GET /v3/session/{sessionId}/decision/); otherwise a transient correlation UUID.

​
age_estimation
object
​
vendor_data
string | null

Echo of the vendor_data you sent, or null.

​
metadata
object

Echo of the metadata object you sent, or null.

​
created_at
string<date-time>

ISO 8601 timestamp (UTC) of when the response was generated.