Liveness Check

Challenge-response liveness verification to ensure a real person is present. Sessions generate 2-3 random challenges (turn head, blink, smile, etc.) that the user must complete by submitting photos.

POST/verifications/liveness/session

Create a new liveness session with random challenges. Sessions expire after 10 minutes.

Request Body

Parameter	Type	Description
`userId`required	string	User ID for this liveness check

curl -X POST https://api.verifyhq.com/v1/verifications/liveness/session \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_123"}'

Response

201 Createdjson

{
  "sessionToken": "ses_abc123def456",
  "expiresAt": "2025-01-15T10:40:00Z",
  "challenges": [
    {
      "id": "ch_001",
      "type": "TURN_LEFT",
      "instruction": "Turn your head to the left"
    },
    {
      "id": "ch_002",
      "type": "SMILE",
      "instruction": "Smile naturally"
    }
  ],
  "instructions": "Submit a photo for each challenge using POST /verifications/liveness/challenge. Complete all challenges within 10 minutes."
}

POST/verifications/liveness/challenge

Submit a photo completing a specific challenge. When all challenges are submitted, verification runs automatically.

Max file size: 10MB. Accepted formats: JPEG, PNG, WebP, HEIC.

Form Fields

Parameter	Type	Description
`sessionToken`required	string	Session token from POST /session
`challengeId`required	string	Challenge ID to submit for
`photo`required	file	Photo completing the challenge

Examplebash

curl -X POST https://api.verifyhq.com/v1/verifications/liveness/challenge \
  -H "X-API-Key: your_api_key" \
  -F "sessionToken=ses_abc123def456" \
  -F "challengeId=ch_001" \
  -F "photo=@turn_left.jpg"

Response (In Progress)

200 OKjson

{
  "sessionToken": "ses_abc123def456",
  "status": "IN_PROGRESS",
  "challengesCompleted": 1,
  "challengesTotal": 2,
  "isComplete": false,
  "nextStep": "Submit photo for remaining 1 challenge(s)"
}

Response (All Submitted)

200 OK — Completejson

{
  "sessionToken": "ses_abc123def456",
  "status": "COMPLETED",
  "challengesCompleted": 2,
  "challengesTotal": 2,
  "isComplete": true,
  "result": {
    "isAlive": true,
    "confidence": 0.95,
    "antiSpoofScore": 0.98,
    "faceMatchScore": 0.92,
    "failureReason": null
  }
}

POST/verifications/liveness/reference-selfie

Upload a reference selfie to compare against challenge photos for face matching.

Form Fields

Parameter	Type	Description
`sessionToken`required	string	Session token
`selfie`required	file	Clear, front-facing selfie

GET/verifications/liveness/:id

Retrieve a liveness check by ID.

GET/verifications/liveness/user/:userId

List all liveness checks for a user. Supports page and limit query params.

Challenge Types

Parameter	Type	Description
`TURN_LEFT`	challenge	Turn head to the left
`TURN_RIGHT`	challenge	Turn head to the right
`LOOK_UP`	challenge	Look upward
`SMILE`	challenge	Smile naturally
`BLINK`	challenge	Blink both eyes
`OPEN_MOUTH`	challenge	Open mouth slightly