Flows

A flow is a declarative, ordered set of verification steps with a decision rule. Instead of calling individual checks yourself, define a flow once and let the API run its steps and compute the overall outcome — including routing to manual review when needed.

Modules

A step's module is one of:

document_liveness · selfie_liveness · active_liveness · deepfake · face_match · aml

Create a flow

POST /flows

curl -X POST https://api.dev.valydar.com/flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "onboarding",
    "description": "Document + selfie + AML",
    "steps": [
      { "id": "doc",   "module": "document_liveness", "required": true },
      { "id": "selfie","module": "face_match",        "required": true },
      { "id": "aml",   "module": "aml",               "required": false }
    ],
    "decision": { "strategy": "require_all" }
  }'

Field	Type	Description
name	string	Flow name
description	string	Optional description
steps[].id	string	Unique step id (used in results and webhooks)
steps[].module	string	One of the modules above
steps[].required	boolean	Required steps must pass; an optional step failing degrades the outcome to warn
steps[].config	object	Optional per-step overrides, e.g. {"threshold": 0.6}
decision.strategy	string	require_all or require_any

Response 201:

{ "id": "flw_...", "name": "onboarding", "description": "Document + selfie + AML", "steps": 3, "decision": "require_all" }

Manage flows

GET    /flows            # list
GET    /flows/{id}       # get definition
DELETE /flows/{id}       # delete

Start a run

POST /flows/{id}/runs

curl -X POST https://api.dev.valydar.com/flows/flw_.../runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"client_reference": "order-8842"}'

Starting a run creates a linked verification. The run is in_progress until its final step completes; the verification is only finalized once the run is terminal (with the flow's decision).

Run a step

POST /flows/{id}/runs/{run_id}/steps/{step_id}

curl -X POST https://api.dev.valydar.com/flows/flw_.../runs/flr_.../steps/selfie \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"document_id": "doc_...", "selfie_id": "slf_..."}'

Field	Used by	Description
document_id	document checks	Uploaded document artifact
selfie_id	selfie/face checks	Uploaded selfie artifact
name	aml	Name to screen
challenge_type	active_liveness	blink · turn_left · turn_right · nod · smile (random if omitted)
frames	active_liveness	Base64 frames (≥ 2)

The final step records itself, merges the flow decision into the linked verification, and marks the run terminal in one atomic operation; a concurrent finisher is rejected with 400.

Get a run

GET /flows/{id}/runs/{run_id}

Returns the run status (in_progress | passed | failed) and per-step results. GET /flows/{id}/runs lists runs.

Outcome → review

A flow that does not fully pass routes the session to the review queue. See Case Management & Review.

Webhooks

Flow progress fires flow.step.completed per step and flow.completed with the computed decision. See Webhooks.