Create a verification session

Headers

• Idempotency-Keystring1–255 chars

  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.

Request bodyapplication/json

• workflow_idstring | null

  A published workflow of your organization.

• vendor_datastring | null≤ 256 chars

  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.

• metadataobject | null

  Your JSON, up to 16 KB. Returned in webhooks and results. Stored as plain JSON: do not put sensitive personal data here.

• callback_urlstring | nulluri≤ 2048 chars

  https URL the person is sent back to at the end.

• languagestring | null

  One ofendefrit

• contactobject | null

  Prefills the email and phone steps of the workflow.

  Show 2 child propertiesHide child properties

  • emailstring | null≤ 254 chars
  • phonestring | null≤ 32 chars

    E.164, e.g. +41791234567.

• reusableboolean | null

  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.

• typestring | null

  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 ofverificationreauth

• send_linkstring | null

  Also send the hosted link to contact.email or contact.phone, in the session's language. Organization keys only.

  One ofemailsms

• sandbox_scenariostring | null

  sk_test_ keys only. The session finishes at once with this outcome, with the usual webhook and signed result. Free; nothing is captured.

  One ofapproveddeclined_tampereddeclined_expireddeclined_unreadabledeclined_face_mismatchreview_livenessreview_amlreview_documentcheck_error

• expected_detailsobject | null

  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.

  Show 9 child propertiesHide child properties

  • first_namestring | null
  • last_namestring | null
  • date_of_birthstring | null
  • nationalitystring | null
  • document_countrystring | null
  • document_numberstring | null
  • address_countrystring | null
  • address_postal_codestring | null
  • address_localitystring | null

Responses

• 200The session. A replayed response carries the header idempotent-replayed: true; a returned open session carries secuveri-session-reused: true.

  • session_idstringuuidrequired
  • verification_idstringrequired
  • statusstringrequired

    One ofCREATEDDOC_PROCESSINGMRZ_FOUNDNFC_PROCESSINGDOC_DONESELFIE_PROCESSINGSELFIE_DONECOMPLETEFAILEDREVIEW_REQUIREDCHECK_ERROREXPIRED

  • created_atstringdate-timerequired
  • session_tokenstringrequired

    Grants the person's browser access to this session.

  • urlstring | null

    The hosted verification link.

  • sandbox_scenariostring

    Echoed when the session was finished by a scenario.

  • link_sentobject

    Present when send_link was requested, including on reused sessions. queued means durably accepted for background delivery, not sent or delivered; cooldown means a pending job, the 30-second resend interval, or the five-per-hour limit prevents another send.

    Show 2 child propertiesHide child properties

    • channelstring

      One ofemailsms

    • statusstring

      One ofqueuedcooldownsentfailedunavailable

  • referenceobject

    type reauth: whose stored face is the reference.

    Show 2 child propertiesHide child properties

    • verification_idstring
    • sourcestring

      One ofstored_chipstored_selfiestored_document

  • reusedboolean

    true when an unfinished session for the same vendor_data and workflow_id was returned instead of a new one.

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