Sessions

A session is one applicant going through one workflow. Create it on your backend with a secret key; everything the frontend needs is in the response.

Create a sessionCopy Anchor Link

// Your frontend calls this, then passes { clientToken, sessionUrl } to @okyc/web or @okyc/react.
app.post('/api/kyc/session', express.json(), async (req, res) => {
  const userId = req.header('x-user-id') ?? 'demo-user'; // use your own auth here
  try {
    const session = await okyc.sessions.create(
      {
        workflowId: process.env.OKYC_WORKFLOW_ID,
        referenceId: userId,
        redirectUrl: process.env.REDIRECT_URL,
      },
      { idempotencyKey: `kyc-${userId}-${new Date().toISOString().slice(0, 10)}` },
    );
    res.json({ clientToken: session.clientToken, sessionUrl: session.url });
  } catch (e) {
    res.status(e.statusCode ?? 500).json({ error: e.code ?? 'error' });
  }
});

The full schema is in the API reference. Send an Idempotency-Key so a retried request doesn't create a second session.

The response:

{
  "id": "ses_…",
  "status": "created",
  "url": "https://verify.okyc.stream/s/ses_…#t=st_…",
  "client_token": "st_…",
  "expires_at": "2026-10-08T09:30:00.000Z"
}

• Pass url to a mobile SDK, or client_token + url to @okyc/web / @okyc/react.
• The client token is valid for 30 minutes, sliding while the applicant is active. To resume later, issue a new one with POST /v1/sessions/:id/client_token; the flow continues at the first unfinished step.
• Don't log the url: it carries the token.

Read the resultCopy Anchor Link

curl "https://api.okyc.stream/v1/sessions/ses_…?expand=checks,applicant" \
  -H "Authorization: Bearer $OKYC_SECRET_KEY"

status is the session's state (statuses); decision and decision_source (auto or manual) say how it was decided. expand=checks adds every check with its result; expand=applicant (KYC) or expand=business (KYB) adds the verified profile.

Fetch a session when a webhook arrives rather than polling.

List sessionsCopy Anchor Link

GET /v1/sessions?status=review&limit=50 returns a page (data, has_more). Pass the last id as starting_after for the next page, or filter by reference_id. @okyc/node iterates every page for you: for await (const s of okyc.sessions.list({ status: 'review' })).

Other actionsCopy Anchor Link

Evidence files are served for download: images (JPEG, PNG, WebP) inline, everything else — PDFs, ZIPs — as an attachment with Content-Type: application/octet-stream and a sandboxing Content-Security-Policy, so a malicious document can never run in a browser. Every upload is virus-scanned before it is stored.

Direct checks (no hosted flow)Copy Anchor Link

Run a single check server-to-server, for example to re-verify a PAN you already hold:

curl https://api.okyc.stream/v1/checks/in.pan.verify \
  -H "Authorization: Bearer $OKYC_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "pan": "ABCPE1234F" }'

Use a country key (in.pan.verify) or a generic key with country (tax_id.verify + "country": "IN"). ?async=true returns 202 and sends check.completed when done. GET /v1/capabilities?country=IN lists what a country supports.