Workflows define the steps a customer goes through in a KYC session — which documents to capture, whether to run a liveness check, which forms to fill, and the rules applied at each step. Form templates define the custom forms a workflow can include.
Requires the KYC Sessions product on your API key. Creating workflows additionally requires the Workflow Creation feature; creating or editing form templates requires the Form Builder feature.
Workflows
Listing Workflows
Code
Returns all public (Dossiers-provided) workflows plus your organization's own private workflows. Use a workflow's id as workflowId when creating a session.
Creating a Workflow
Code
Creates a private workflow for your organization with your chosen steps and configuration.
Step Defaults
Code
Returns the default input, rules, and metadata for every available step type. Use this to pre-populate a workflow builder UI before customizing each step.
Liveness challenge types
The liveness step's config.challengeType selects how presence is proven:
challengeType | What the customer does | Server-side verdict |
|---|---|---|
selfie | Holds a centred, well-lit face still for a few seconds | None — capture only |
distance | Moves closer, then further away | None — capture only |
color-flash | Holds still while the screen flashes a random colour sequence issued by the server | Yes — the face's reflection is matched against the issued sequence; a replay or injected stream cannot answer a nonce it has never seen |
color-flash accepts two extra knobs: flashSlotCount (3–12 colours, default 6) and flashSlotMs (400–1500 ms per colour, default 500). Its verdict surfaces in the session's verification.biometrics.liveness as method: "COLOR_FLASH" plus a colorFlash block, and as a color-flash-challenge entry in verification.checks. A weak reflection routes to REVIEW rather than declining the customer, and when the face was already in strong ambient light (daylight, a window behind the camera — reported as environment: "bright" with the measured ambientLuma) it becomes a non-blocking WARNING, since no screen can compete with that. Only a strong reflection of the wrong sequence fails.
Updating a Workflow
Code
Updates the workflow in place and bumps its version number. Existing sessions are unaffected — each session runs against the workflow snapshot captured when it was created.
Deleting a Workflow
Code
Returns 204 No Content. Sessions already created from the workflow keep their snapshot and continue to work.
Workflow Claims
Claims are the values a workflow cross-checks against the captured document — the customer's name, date of birth, ID number, address. Instead of wiring per-step input mappings, declare each claim once at the workflow level with a source, and every document-bearing step whose processor supports that field automatically verifies it.
Code
Claim fields and vocabulary
field must be a canonical claim key from the claim vocabulary of the
workflow's document types (e.g. name, dateOfBirth, idNumber, address
for the Sri Lanka NIC processor). GET /kyc-workflows/editor-config returns
the vocabulary per document type — each entry carries the field, its value
type (string or ISO date), and a description. Declaring a field outside
the vocabulary of your workflow's document types is rejected at save time.
Claim sources
| Source | Meaning |
|---|---|
{ "kind": "session" } | You assert the value at session creation via the claims request field. Set required: true to reject session creation when the value is missing |
{ "kind": "step", "stepId", "path" } | The value is read from another step's output — typically a form answer, e.g. formData.date_of_birth |
Step order does not matter. Claims are compared by the session-level checks after the customer finishes the whole flow, when every step's output exists — a form that runs after the document step is as good a source as one that runs before it.
If you declare nothing: automatic inference
Undeclared claims are not silently skipped. When a supported claim has no declared value, the platform infers one from the session's completed forms using a curated, deterministic table — never fuzzy matching:
| Canonical field | Recognized form-field names (case/format-insensitive) | Composition |
|---|---|---|
name | name, full_name, applicant_name, customer_name | first_name + middle_name + last_name joined |
dateOfBirth | date_of_birth, dob, birth_date, birthday | — |
idNumber | id_number, nic, nic_no, national_id, passport_number, … | — |
address | address, full_address, home_address, … | address lines + city + province + postal code joined |
A declared value always wins over inference, and a lone fragment (a first name alone, a city alone) is never passed off as the whole claim.
Where claim results land
Each comparison surfaces in the session's normalized
verification object: a per-field
verdict in checks (e.g. name-match, dob-match) and the claimed-vs-extracted
pair with match confidence in provenance. A claim with nothing to compare on
either side reports NOT_EXECUTED — never a failure.
Form Templates
Form templates are reusable form definitions (fields, validation, layout) that workflow form steps reference.
| Endpoint | Description |
|---|---|
GET /form-templates | List your organization's form templates |
GET /form-templates/{id} | Get a form template |
POST /form-templates | Create a form template (requires Form Builder) |
PUT /form-templates/{id} | Update a form template (requires Form Builder) |
DELETE /form-templates/{id} | Delete a form template (returns 204) |
See the API Reference for the full request and response schemas of each endpoint.