Getting Started

End-to-End Guide: Your First KYC Flow

Copy page

This guide builds a complete identity-verification flow from nothing, in the order you'd actually do it: a form template, a workflow that uses it, a session your customer completes, webhooks that tell you when it's done, and the result you act on. Every request below is runnable — open the API Reference to try each one interactively with your own token.

Prerequisites: an API key with the KYC Sessions product, plus the Workflow Creation and Form Builder features for steps 1–2. See Authentication.

The example flow: the customer fills a short personal-details form, captures a Sri Lanka NIC, and passes a liveness challenge. The platform cross-checks what they typed against what their document says, and their face against the document portrait.

1. Create a Form Template

Templates define the custom forms a workflow can show. Name the fields well — recognized names (first_name, date_of_birth, nic_no, …) let the platform wire them into document cross-checks automatically.

Code
curl -X POST https://api.dossiers.wiki/form-templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Person Information",
    "description": "Basic personal details for identity verification",
    "fields": [
      { "id": "first_name",    "type": "text", "label": "First Name",    "required": true },
      { "id": "last_name",     "type": "text", "label": "Last Name",     "required": true },
      { "id": "date_of_birth", "type": "date", "label": "Date of Birth", "required": true },
      { "id": "nic_no",        "type": "text", "label": "NIC Number",    "required": true }
    ]
  }'

Keep the returned template id — the workflow's form step references it.

2. Create a Workflow

A workflow is an ordered list of steps plus routing rules and claims — the values to verify against the captured document. Steps chain via rules.onSuccess (the next stepId, or COMPLETE_SESSION to finish); onFailure: "FAIL_SESSION" ends the session as failed once retries are exhausted.

Code
curl -X POST https://api.dossiers.wiki/kyc-workflows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Onboarding (LK)",
    "steps": [
      {
        "stepId": "person-info",
        "type": "form_collection",
        "input": { "config": { "templateId": "TEMPLATE_ID_FROM_STEP_1" } },
        "output": {},
        "rules": { "onSuccess": "id-verify", "onFailure": "FAIL_SESSION" }
      },
      {
        "stepId": "id-verify",
        "type": "id_verification",
        "input": {
          "config": {
            "strategy": "document_based",
            "allowedDocuments": { "LKA": ["LKA_NIC"] },
            "maxSubmissions": 3
          }
        },
        "output": {},
        "rules": { "onSuccess": "live-check", "onFailure": "FAIL_SESSION" }
      },
      {
        "stepId": "live-check",
        "type": "liveness",
        "input": { "config": { "challengeType": "distance", "timeLimitSeconds": 60 } },
        "output": {},
        "rules": { "onSuccess": "COMPLETE_SESSION", "onFailure": "FAIL_SESSION" }
      }
    ],
    "claims": [
      { "field": "dateOfBirth", "source": { "kind": "session" }, "required": true },
      { "field": "name",     "source": { "kind": "step", "stepId": "person-info", "path": "formData.first_name" } },
      { "field": "idNumber", "source": { "kind": "step", "stepId": "person-info", "path": "formData.nic_no" } }
    ]
  }'

Two things worth understanding here:

• Claims declare what gets cross-checked and where the trusted value comes from: dateOfBirth you assert at session creation; name and idNumber come from the customer's own form answers. Step order doesn't matter — the comparisons run after the flow ends. Full model: Workflow Claims.
• The workflow is versioned and snapshotted — editing it later never affects sessions already in flight.

Keep the returned workflow id.

3. Create a Session

Code
curl -X POST https://api.dossiers.wiki/kyc-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "externalId": "usr_abc123",
      "name": "Nimesha Periyapperuma",
      "email": "customer@example.com"
    },
    "workflowId": "WORKFLOW_ID_FROM_STEP_2",
    "expiresInMs": 86400000,
    "claims": { "dateOfBirth": "1990-01-15" }
  }'

The claims object supplies every session-sourced claim the workflow declared; a missing required claim rejects the request with a 400. The response carries the session and the customer's entry point:

Code
{
  "session": { "id": "665f1a2b3c4d5e6f7a8b9c0d", "status": "not-started", ... },
  "token": "eyJhbGciOi...",
  "sessionUrl": "https://kyc.example.com/kyc/665f1a2b...?token=eyJ..."
}

4. Hand Off to the Customer

Send the customer to sessionUrl — or do nothing: when you provided name and email, an invitation email with the link and a QR code was already sent. The hosted flow walks them through the form, document capture, and liveness challenge, with retries up to each step's maxSubmissions.

5. Listen for the Outcome

Register a webhook destination for the kycSessions.* events. For a session that completes, you will see (in order):

1. kycSessions.step.completed — per step, as the customer progresses.
2. kycSessions.session.completed — the customer finished the flow. Not the final verdict: the cross-step checks (claims comparison, face match) run after this.
3. kycSessions.session.checksCompleted — the check run settled. Its payload carries the now-final outcome and any blockingReasons:

Code
{
  "data": {
    "kycSessionId": "665f1a2b3c4d5e6f7a8b9c0d",
    "version": 1,
    "outcome": "APPROVED",
    "blockingReasons": [],
    "partial": false
  }
}

Act on the highest version you've seen — late-arriving evidence can trigger a superseding run. Payloads are PII-free by design; fetch detail with the read API below.

6. Read the Result

Code
curl https://api.dossiers.wiki/kyc-sessions/665f1a2b3c4d5e6f7a8b9c0d \
  -H "Authorization: Bearer YOUR_API_KEY"

Consume the verification object — the normalized, versioned contract — and switch on verification.outcome:

Outcome	What to do
APPROVED	Activate the customer
DECLINED	Inspect decision.reasons — normalized codes like DATA_MISMATCH, FACE_MISMATCH, DOCUMENT_TAMPERED
IN_REVIEW	A human reviewer decides; wait for session.reviewed
RESUBMISSION_REQUESTED	A retryable failure (e.g. blurry capture) — the customer can try again from the same sessionUrl

For the cross-check detail, read verification.checks (per-rule verdicts — name-match, dob-match, face-match, …) and verification.provenance (the claimed-vs-extracted value pair behind each comparison).

7. Do It Typed

Everything above ships in the @dossier-wiki/cloud-sdk package — typed request/response shapes, a webhook router with signature verification, and typed event payloads:

Code
import { DossiersAPIService, DossiersWebhookRouter } from "@dossier-wiki/cloud-sdk";

const api = new DossiersAPIService({ apiKey: process.env.DOSSIERS_API_KEY! });

const { session, sessionUrl } = await api.kyc.sessions.create({
  customer: { externalId: "usr_abc123", email: "customer@example.com", name: "..." },
  workflowId: "WORKFLOW_ID",
  claims: { dateOfBirth: "1990-01-15" },
});

Data retention

Your organization has a data retention window: once a record is older than that window, it and everything attached to it are permanently deleted. The window is configured per organization by Dossiers — tell us how many days you need, or ask for never to keep your data indefinitely. Organizations without a configured window keep everything.

Age is measured from a record's creation, not its last update: a session created 100 days ago is deleted by a 90-day window even if it was reviewed yesterday. A clearing process runs daily and only ever touches records past the window.

Work in progress is never deleted, however old it is. A session your customer can still open, a document check still running, and a batch still being screened are all skipped until they finish — so a retention window can never break someone part-way through onboarding. They become eligible once they settle (or, for a session, once its expiry passes).

What is deleted, with everything each one owns:

Record	Also deleted
KYC sessions	Captured media, document-pipeline artifacts, exported reports, check runs, comments, device observations
Screening batches	Their screening requests, alerts, alert comments, exports
Single screening requests	Their alerts and comments
Document-processing instances	Uploaded originals, crops and detected faces
Device observations	—
Webhook delivery logs	—
API usage logs	—

What is not deleted by age, because your live integration depends on it: workflows, form templates, API keys and webhook destinations. These are removed only when an organization is closed and its data erased in full.

Deletion is irreversible and leaves no copy in Dossiers Cloud. Anything you or another Dossiers product has already copied out — an archived report, a customer profile in Dossiers OS — is yours to manage under your own retention rules; this window governs the Cloud API's own records. Afterwards reads of a deleted record return 404, and for each deleted session you receive a kycSessions.session.purged webhook with trigger: "retention" — so if you need to keep evidence beyond your window, archive it on your side before then.

Where to Go Deeper

• KYC Sessions — lifecycle, results, attempts & device intelligence
• KYC Workflows & Form Templates — step types, claims, versioning
• Webhooks — signatures, retries, every event payload
• API Reference — every endpoint, interactive