cURL

curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'user_image=@./selfie.jpg' \
  -F 'face_liveness_score_decline_threshold=30' \
  -F 'save_api_request=true' \
  -F 'vendor_data=user-123'

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

Biometrics & Face

Passive Liveness

Detect presentation attacks — printed photos, screen replays, masks, deepfakes — from a single face image. No video, motion, or user interaction required.

How it works. The image is analyzed by a biometric model; the largest detected face is evaluated and a liveness score (0–100) is computed. status is Declined when any error-severity warning fires:

NO_FACE_DETECTED — the liveness model found no face,
LOW_LIVENESS_SCORE — score at or below face_liveness_score_decline_threshold (default 30),
LIVENESS_FACE_ATTACK — the model detected a presentation attack,
FACE_IN_BLOCKLIST / POSSIBLE_FACE_IN_BLOCKLIST — the face matches an entry on your face blocklist.

MULTIPLE_FACES_DETECTED is a warning-severity signal (does not decline), and DUPLICATED_FACE / POSSIBLE_DUPLICATED_FACE are information-severity signals that the same face already appeared in another approved session (they never decline). face_quality and face_luminance (0–100, nullable) describe capture quality.

Blocklist and duplicate screening. Runs on every call — with or without save_api_request — by matching the detected face against your application’s face search index. Prior faces with the same vendor_data are excluded from the entire index search — so re-running liveness for the same user does not trigger DUPLICATED_FACE, and a blocklisted face originating from a session with the caller’s own vendor_data is also NOT flagged (FACE_IN_BLOCKLIST screening is bypassed for same-vendor_data faces).

Billing. Each 200 response consumes one Passive Liveness API credit (standalone APIs have no free tier). Insufficient balance returns 403 before any image processing.

Session persistence and face enrollment (save_api_request, default true). When true, the call is persisted as an API-type session (Business Console, GET /v3/session/{sessionId}/decision/ via the returned request_id, status.updated webhook), the reference image and face crop are stored, and the detected face is enrolled into your face search index so later Face Search calls and duplicate checks can match it. When false, the call is one-shot: nothing is stored and the face is not enrolled (blocklist/duplicate screening still runs).

Sandbox. Sandbox API keys skip all processing and billing: after request validation (malformed input still returns 400), the endpoint returns a static Approved mock payload, no session is persisted, and no credits are consumed.

Authentication. Send your application’s API key in the x-api-key header. Missing or invalid credentials return 403 ({"detail": "You do not have permission to perform this action."}) — this API never returns 401.

Rate limit. Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns 429.

POST

passive-liveness

cURL

curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'user_image=@./selfie.jpg' \
  -F 'face_liveness_score_decline_threshold=30' \
  -F 'save_api_request=true' \
  -F 'vendor_data=user-123'

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

Authorizations

x-api-key

string

header

required

Body

multipart/form-data

user_image

file

required

Front-facing face image (e.g. a selfie). Allowed extensions: tiff, jpg, jpeg, png, webp. Maximum upload size: 5 MB (larger files are rejected with 400). Images are automatically compressed to ~0.5 MB before processing, so very high resolutions do not improve accuracy. The image should contain a single subject — when several faces are present, the largest one is evaluated and a MULTIPLE_FACES_DETECTED warning is added.

face_liveness_score_decline_threshold

number<float>

default:30

Liveness score threshold (0–100). A computed score at or below this value emits a LOW_LIVENESS_SCORE warning and sets status to Declined. Default 30; raise it for a stricter anti-spoofing posture. Values outside 0–100 return 400.

Required range: 0 <= x <= 100

Example:

30

rotate_image

boolean

default:false

When true, the service tries 90-degree rotations of the input and uses the orientation that yields the best face detection. Useful when EXIF orientation is missing. Adds latency.

Example:

false

save_api_request

boolean

default:true

When true (default), persists the call as an API-type session, stores the face images, emits a status.updated webhook, and enrolls the detected face into your face search index. When false, the call is one-shot — nothing is stored and the face is not enrolled. Blocklist and duplicate screening run either way.

Example:

true

vendor_data

string

Optional opaque identifier (your user id, email, UUID…) stored on the persisted session and echoed back. Also used to exclude prior sessions with the same vendor_data from the duplicate-face check, so re-verifying the same user does not raise DUPLICATED_FACE.

Example:

"user-123"

metadata

object

Optional JSON object stored with the session (when save_api_request=true) and echoed back. In multipart requests, send it as a JSON-encoded string field — it is parsed into an object.

Example:

{ "flow": "withdrawal" }

Response

Passive liveness completed. liveness.score is the model's 0–100 confidence that the image shows a live person; status is Approved unless an error-severity warning fired. A spoofed or blocklisted face still returns 200 — inspect liveness.status and liveness.warnings, 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.

liveness

object

Show child attributes

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, e.g. 2026-06-12T01:04:42.763237+00:00.

Venezuela - Cédula verification Face Match

⌘I