Dark
Request a walkthrough
On this page
Developer overview

KYC Hosted Sessions

A hosted KYC session is a one-shot verification link your backend mints server-side and hands to your end customer (redirect, email, or QR). The customer completes identity verification on Noxtica’s hosted page; your backend never receives the session’s bearer token or the customer’s raw answers directly.

Key points

  1. A one-shot linkYour backend mints the hosted session server-side and hands it to your end customer by redirect, email, or QR.
  2. The window narrows when it is openedOnce the customer opens the link, the capture window is counted from that open, not from when your backend minted the link.
  3. Expiry is terminalStop polling or retrying an expired session, and mint a new one if the customer still needs to complete verification.
  1. Session lifetime
  2. After expiry
  3. Related reading
How this page is organisedBar length shows each section’s share of the text. Select a section to jump to it.

Session lifetime

An unopened link keeps its normal default validity. Once the customer opens it, the capture window narrows to 30 minutes from that first open — not from when your backend minted the link. Both the customer-facing session view and your backend’s own session status read carry openedAt (when the customer first opened the link, or absent if they have not yet) and expiresAt (the session’s current effective expiry), so either side can tell which state a session is in without guessing.

  • Your backend

    Mints and reads the session

  • Your end customer

    Opens the link

  • Noxtica

    Hosted verification page

  1. Minted

    Your backend mints the link server-side and hands it to your end customer. The session bearer token and the raw answers never reach your backend directly.

  2. Unopened

    An unopened link keeps its normal default validity. The session read carries openedAt as absent.

  3. Opened

    The capture window narrows, counted from the open. Both session reads carry openedAt and expiresAt, so either side can tell which state a session is in without guessing.

  4. Expired

    The capture window lapses. Customer-facing routes answer with an expired error, while your backend status read keeps succeeding with status expired.

  5. Mint a new one

    Treat the expired answer as terminal: stop polling or retrying that session, and mint a new one if the customer still needs to complete verification.

The life of a hosted KYC session, from minting to a new session

After expiry

Once a session’s capture window lapses, its 5 customer-facing routes — session view, progress, submit, evidence upload, and evidence finalize — each return an HTTP 410 Gone with:

{ "error": "session_expired", "code": "kyc_session_expired", "requestId": "..." }

Your backend’s own session status read (GET /v1/kyc/sessions/{sessionId}) is not one of these: it keeps returning 200 with status: "expired", so a polling backend can observe the terminal state without special-casing an error response.

Treat a 410 from any customer-facing route as terminal: stop polling or retrying against that session, and mint a new one if the customer still needs to complete verification.

Customer-facing routes

Each route answers with a Gone response carrying the session_expired error, the kyc_session_expired code, and a request id.

Routes that answer this way

  • Session view
  • Progress
  • Submit
  • Evidence upload
  • Evidence finalize

What to do

  • Treat it as terminal: stop polling or retrying against that session.
  • Mint a new session if the customer still needs to complete verification.

Your backend status read

Your backend’s own session status read is not one of those routes. It keeps returning success with status expired.

Why it differs

  • A polling backend can observe the terminal state without special-casing an error response.
After expiry: what the customer-facing routes return and what your status read returns