POST /verify/sessions/{id}:submit-liveness

Guided face captures vs registry portrait (X-Verify-Token)

Bearer API key or staff session application/json operation submitVerifyLiveness

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	—

Request

Content type: application/json · required

Field	Type	Required	Description
`images`	array of any	Yes	downscaled client data-URL frames (JPEG/PNG/WEBP, 512KB each, max 8)
`gestures`	array of string	No	—
`portrait`	string	No	registry portrait echoed back as reference (optional)
`detection`	string	No	which capture path ran; upload is rejected (422 liveness.uploads_disabled) unless the session config opted in with uploads_allowed:true one of `measured`, `timed`, `upload`
`scores`	array of object	No	per-gesture measured readings (smile, yaw, manual) — stored, not decisioned

curl -X POST "$MONICHEK_API/verify/sessions/{id}:submit-liveness" \
  -H "Authorization: Bearer $MONICHEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "images": [],
  "gestures": [
    "string"
  ],
  "portrait": "string",
  "detection": "measured",
  "scores": [
    {}
  ]
}'

const res = await fetch(`${MONICHEK_API}/verify/sessions/{id}:submit-liveness`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${MONICHEK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "images": [],
    "gestures": [
      "string"
    ],
    "portrait": "string",
    "detection": "measured",
    "scores": [
      {}
    ]
  }),
});

const data = await res.json();

import os
import requests

res = requests.post(
    f"{os.environ['MONICHEK_API']}/verify/sessions/{id}:submit-liveness",
    headers={"Authorization": f"Bearer {os.environ['MONICHEK_API_KEY']}"},
    json={
      "images": [],
      "gestures": [
        "string"
      ],
      "portrait": "string",
      "detection": "measured",
      "scores": [
        {}
      ]
    },
)
print(res.json())

$ch = curl_init(getenv('MONICHEK_API') . '/verify/sessions/{id}:submit-liveness');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('MONICHEK_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'images' => [],
        'gestures' => [
            'string',
        ],
        'portrait' => 'string',
        'detection' => 'measured',
        'scores' => [
            [],
        ],
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Replace {id} with the resource id.

Responses

200 OK completed session with liveness verdict (weak signal downgrades combined to review) application/json

{
  "object": "verify_result",
  "status": "completed",
  "session_id": "vs_01M3R...",
  "combined_decision": "approved",
  "risk_rating": "low",
  "liveness_decision": "pass",
  "liveness_score": 0.95
}

Error responses

Status	Meaning	Body
401	Unauthorized	RFC 9457 problem
409	Conflict	RFC 9457 problem
422	Unprocessable Entity	validation failed — or liveness.uploads_disabled when detection is upload without config.uploads_allowed:true

Errors use the RFC 9457 problem format with a stable code.