# `POST /v1/sessions` — Create a verification session

Returns a hosted link to send the person to. With workflow_id the session runs that published workflow of your organization; without it, the full verification.

Parameters:
- `Idempotency-Key` (header, string): 1 to 255 visible ASCII characters. Retrying with the same key and body within 24 hours returns the first response instead of creating a second session.

Body:
- `workflow_id` (string, nullable): A published workflow of your organization.
- `vendor_data` (string, nullable): Your id for the person. Returned in webhooks and results. While a session for the same vendor_data and workflow_id is unfinished, creating again returns it.
- `metadata` (object, nullable): Your JSON, up to 16 KB. Returned in webhooks and results. Stored as plain JSON: do not put sensitive personal data here.
- `callback_url` (string, nullable): https URL the person is sent back to at the end.
- `language` (string, nullable) One of `en`, `de`, `fr`, `it`.
- `contact` (object, nullable): Prefills the email and phone steps of the workflow.
  - `email` (string, nullable)
  - `phone` (string, nullable): E.164, e.g. +41791234567.
- `reusable` (boolean, nullable): The person may present their secuveri ID (secuveri Wallet) instead of capturing a document; a new liveness selfie is matched against its portrait. Needs Liveness Check and Face Match in the workflow; not with AML screening, proof of address or age estimation (422). 503 when reusable verification is not available.
- `type` (string, nullable): reauth: a selfie with liveness matched against the face of the customer's last approved verification (needs vendor_data). 409 no_reference when no stored face remains. One of `verification`, `reauth`.
- `send_link` (string, nullable): Also send the hosted link to contact.email or contact.phone, in the session's language. Organization keys only. One of `email`, `sms`.
- `sandbox_scenario` (string, nullable): sk_test_ keys only. The session finishes at once with this outcome, with the usual webhook and signed result. Free; nothing is captured. One of `approved`, `declined_tampered`, `declined_expired`, `declined_unreadable`, `declined_face_mismatch`, `review_liveness`, `review_aml`, `review_document`, `check_error`.
- `expected_details` (object, nullable): Who you expect. A field that disagrees with the document sends the verification to review (EXPECTED_DETAILS_REVIEW). Dates as YYYY-MM-DD, countries as ISO alpha-3. The address fields are not on identity documents and are never compared with them: the FINMA profile uses them for its digital address evidence (country against the IP country; Swiss postal code and locality against the official directory) when no proof of address was read.
  - `first_name` (string, nullable)
  - `last_name` (string, nullable)
  - `date_of_birth` (string, nullable)
  - `nationality` (string, nullable)
  - `document_country` (string, nullable)
  - `document_number` (string, nullable)
  - `address_country` (string, nullable)
  - `address_postal_code` (string, nullable)
  - `address_locality` (string, nullable)

Responses:
- 200: The session. A replayed response carries the header idempotent-replayed: true; a returned open session carries secuveri-session-reused: true.
- 401: Missing, unknown or expired API key.
- 402: The balance does not cover the verification (code insufficient_balance or payment_hold).
- 403: The key lacks the scope this call needs, or its IP allowlist refuses the caller.
- 404: workflow_id does not name a workflow of your organization.
- 409: The workflow is not published, a request with this Idempotency-Key is still running, or (type reauth) no stored face remains (code no_reference).
- 422: A field is invalid, the Idempotency-Key was used with a different body, or sandbox_scenario was sent with a live key.
- 429: Too many requests.