# Sessions

`POST https://api-verify.secuveri.com/v1/sessions` with your API key in `x-api-key`. Every field is optional.

| Field | Limit | What it does |
| --- | --- | --- |
| `workflow_id` | a published workflow of your organization | Runs that workflow. A `sk_test_` key runs only sandbox workflows, `sk_live_` only production ones. Without it, the full verification runs. |
| `vendor_data` | ≤ 256 characters | Your id for the person. Returned in webhooks, results and dashboard search. |
| `metadata` | JSON object, ≤ 16 KB | Your data, returned in webhooks and results. Stored as plain JSON: do not put sensitive personal data in it. |
| `callback_url` | https, ≤ 2048 characters | Where the person is sent at the end. |
| `language` | `en`, `de`, `fr`, `it` | The language the page starts in. The person can still switch. |
| `contact` | `email`, `phone` (E.164) | Prefills the email and phone steps of the workflow. |
| `send_link` | `email` or `sms` | Queues the link for that `contact`, in the session's language, including when an open session is reused. `link_sent.status` is `queued`, `cooldown`, `failed` or `unavailable`. Queued means saved for background delivery, not delivered. Repeated sends have a 30-second cooldown and a five-per-hour limit per session/channel. The session remains available even if queueing fails. |
| `expected_details` | `first_name`, `last_name`, `date_of_birth`, `nationality`, `document_country`, `document_number`, `address_country`, `address_postal_code`, `address_locality` | Who you expect; see below. |
| `sandbox_scenario` | `sk_test_` keys only | Finish the session at once with a chosen outcome; see Sandbox. |
| `type` | `verification` (default) or `reauth` | `reauth` checks a returning customer with a selfie only; see Re-authentication. |
| `reusable` | `true` or `false` (default) | The person may share their secuveri ID instead of capturing a document; see Reusable verification. |

### Expected details

Send who you expect to verify, and we compare it with the chip, then the MRZ, then the printed fields. Names are compared ignoring accents and spellings such as Ä/AE. A field that disagrees sends an otherwise approved verification to review with `EXPECTED_DETAILS_REVIEW`; a field the document does not show never holds it. Dates are `YYYY-MM-DD`, countries ISO alpha-3. The signed result has one of `match`, `mismatch` or `unavailable` per field.

### Safe retries

Send `Idempotency-Key` (1–255 visible ASCII characters) to retry a create without making a second session or charge.

| Case | Answer |
| --- | --- |
| Same key and body within 24 hours | The first response, with `idempotent-replayed: true` |
| Same key, different body | 422 |
| Same key while the first request still runs | 409 |
| The first request failed | The key is released; the retry runs normally |

### One open session per customer

While a session for the same `vendor_data` and `workflow_id` is still unfinished, creating another returns that session and its current link, with `reused: true` and the header `secuveri-session-reused: true`. Nothing is charged again, and the first session's settings are kept. Once it finishes, expires or is deleted, the next create starts a new session.

### Statuses

A session moves through processing statuses and ends in one of `COMPLETE`, `FAILED`, `REVIEW_REQUIRED`, `CHECK_ERROR`, `EXPIRED`. `REVIEW_REQUIRED` waits for a reviewer in your dashboard; you get another webhook when they decide.