POST /verify/sessions

Mint a hosted verification session

Bearer API key or staff session application/json operation createVerifySession

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string	No	stable per onboarding; retries replay safely

Request

Content type: application/json

Field	Type	Required	Description
`customer_id`	string	No	—
`config`	object	No	brand_name, brand_color, auto_screen_on_review, liveness_required, uploads_allowed, address_required
`notice_version`	string	No	default `"v1"`
`redirect_url`	string	No	—
`webhook_url`	string	No	—

curl -X POST "$MONICHEK_API/verify/sessions" \
  -H "Authorization: Bearer $MONICHEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_01M3R...",
  "config": {},
  "notice_version": "v1",
  "redirect_url": "https://example.com",
  "webhook_url": "https://example.com"
}'

const res = await fetch(`${MONICHEK_API}/verify/sessions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${MONICHEK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "customer_id": "cus_01M3R...",
    "config": {},
    "notice_version": "v1",
    "redirect_url": "https://example.com",
    "webhook_url": "https://example.com"
  }),
});

const data = await res.json();

import os
import requests

res = requests.post(
    f"{os.environ['MONICHEK_API']}/verify/sessions",
    headers={"Authorization": f"Bearer {os.environ['MONICHEK_API_KEY']}"},
    json={
      "customer_id": "cus_01M3R...",
      "config": {},
      "notice_version": "v1",
      "redirect_url": "https://example.com",
      "webhook_url": "https://example.com"
    },
)
print(res.json())

$ch = curl_init(getenv('MONICHEK_API') . '/verify/sessions');
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([
        'customer_id' => 'cus_01M3R...',
        'config' => [],
        'notice_version' => 'v1',
        'redirect_url' => 'https://example.com',
        'webhook_url' => 'https://example.com',
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Responses

201 Created session with single-use token and hosted_url application/json

{
  "object": "verify_session",
  "session_id": "vs_01M3R...",
  "status": "pending",
  "notice_version": "v1",
  "token": "vs_01M3R....<hmac>",
  "hosted_url": "http://localhost:13201/v/vs_01M3R....<hmac>",
  "token_expires_at": "2026-10-07T12:30:00Z",
  "created_at": "2026-10-07T12:00:00Z"
}

Error responses

Status	Meaning	Body
401	Unauthorized	RFC 9457 problem
422	Unprocessable Entity	validation failed
429	Too Many Requests	RFC 9457 problem

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