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.