Workflows

A workflow defines the verification pipeline for a session — which checks to run, in what order, and how to route based on results. Workflows are directed acyclic graphs (DAGs) where each node is a check, a conditional branch, or a terminal outcome.

How workflows work

When a session enters processing, the workflow engine:

1. Loads the workflow graph assigned to the session (or the org’s default)
2. Starts at the entry node
3. Executes each check node, storing results as it goes
4. Routes through conditional nodes based on check outcomes or extracted data
5. Reaches a terminal node: approved, rejected, or needs_review

The engine supports automatic retries (up to 4 per check), external gates for human-in-the-loop decisions, and percentage-based rollout for canary deployments.

Workflow lifecycle

Workflows are versioned — every edit creates an immutable version snapshot for audit and rollback. Sessions always execute against the version that was active when processing began.

Graph structure

Workflows use a graph format with four node types:

Start node

The entry point. Every workflow has exactly one.

1
{
2
  "start": {
3
    "type": "start",
4
    "next": "document_ocr_step"
5
  }
6
}

Policy node

Executes a verification check. Routes to different nodes based on the outcome.

1
{
2
  "face_match_step": {
3
    "type": "policy",
4
    "policy": "face_match",
5
    "config": {
6
      "security_level": "standard"
7
    },
8
    "on_pass": "age_check_step",
9
    "on_fail": "review_terminal",
10
    "on_error": "review_terminal"
11
  }
12
}

Conditional node

Routes based on extracted data or check results. Evaluates conditions in order and takes the first matching route, with a default fallback.

1
{
2
  "age_gate": {
3
    "type": "conditional",
4
    "routes": [
5
      {
6
        "conditions": [
7
          { "field": "extracted.age", "op": ">=", "value": 21 }
8
        ],
9
        "target": "screening_step"
10
      },
11
      {
12
        "conditions": [
13
          { "field": "extracted.age", "op": ">=", "value": 18 }
14
        ],
15
        "target": "limited_approve"
16
      },
17
      {
18
        "conditions": [],
19
        "target": "reject_underage"
20
      }
21
    ]
22
  }
23
}

Supported operators: >=, <=, >, <, ==, !=, in, not_in, contains, exists.

Terminal node

The final outcome. Every path through the graph must reach a terminal.

1
{
2
  "approve": {
3
    "type": "terminal",
4
    "outcome": "approved"
5
  },
6
  "reject": {
7
    "type": "terminal",
8
    "outcome": "rejected"
9
  },
10
  "review": {
11
    "type": "terminal",
12
    "outcome": "needs_review"
13
  }
14
}

Wait node (external gate)

Pauses the workflow and waits for an external decision via API callback. Useful for integrating with your own decision engine.

1
{
2
  "external_check": {
3
    "type": "wait",
4
    "policy": "external_gate",
5
    "config": {
6
      "timeout_hours": 24,
7
      "on_timeout": "review_terminal"
8
    }
9
  }
10
}

When the workflow pauses, the session status changes to awaiting_external and a session.awaiting_external webhook is fired. Your server can then call the resume endpoint with the decision.

Example workflow

A standard KYC workflow that extracts document data, verifies biometrics, screens against watchlists, and auto-approves or routes to review:

1
{
2
  "entry": "start",
3
  "nodes": {
4
    "start": {
5
      "type": "start",
6
      "next": "ocr"
7
    },
8
    "ocr": {
9
      "type": "policy",
10
      "policy": "document_ocr",
11
      "on_pass": "face_match",
12
      "on_fail": "reject"
13
    },
14
    "face_match": {
15
      "type": "policy",
16
      "policy": "face_match",
17
      "config": { "security_level": "standard" },
18
      "on_pass": "age_check",
19
      "on_fail": "review"
20
    },
21
    "age_check": {
22
      "type": "policy",
23
      "policy": "age_verification",
24
      "config": { "min_age": 18 },
25
      "on_pass": "screening",
26
      "on_fail": "reject"
27
    },
28
    "screening": {
29
      "type": "policy",
30
      "policy": "aml_screening",
31
      "on_pass": "auto_decision",
32
      "on_fail": "review"
33
    },
34
    "auto_decision": {
35
      "type": "policy",
36
      "policy": "auto_approve",
37
      "on_pass": "approve",
38
      "on_fail": "review"
39
    },
40
    "approve": { "type": "terminal", "outcome": "approved" },
41
    "reject": { "type": "terminal", "outcome": "rejected" },
42
    "review": { "type": "terminal", "outcome": "needs_review" }
43
  }
44
}

Data requirements

Workflows declare which data they need from the capture flow:

1
{
2
  "data_requirements": {
3
    "selfie": true,
4
    "liveness": true,
5
    "document": {
6
      "enabled": true,
7
      "accepted_types": ["passport", "drivers_license", "state_id", "national_id"]
8
    },
9
    "user_info": {
10
      "enabled": true,
11
      "fields": ["first_name", "last_name"],
12
      "required_fields": ["first_name", "last_name"],
13
      "verify_phone": false,
14
      "verify_email": false
15
    },
16
    "proof_of_address": {
17
      "enabled": false,
18
      "accepted_types": ["utility_bill", "bank_statement", "council_tax"]
19
    }
20
  }
21
}

The capture UI automatically adjusts to collect the required data. If a workflow requires proof of address, the capture flow adds an additional upload step.

proof_of_address.accepted_types holds canonical document-type keys — utility_bill, bank_statement, council_tax, tax_document, government_letter, and the rest of the proof-of-address vocabulary. Leave it empty to accept everything your organization’s proof-of-address policy allows; the capture flow renders its picker from the resolved list either way.

The proof_of_address_check policy node itself defaults to use organization settings — the policy configured under Settings → Proof of address. Set any of the policy fields in the node’s config to override them for this one workflow; the two layers merge field by field, with the node winning. See Proof of address for the full policy surface and the three-state outcome.

liveness controls the capture-time liveness check (a randomized head-turn pose challenge after the selfie). It defaults to true and only applies when selfie is true and your plan includes liveness detection. Set it to false for a lower-friction flow that captures the selfie without the pose challenge. Some workflows always run the liveness check regardless of this flag — IAL2 workflows, and any workflow containing the Returning User Face Verification policy.

Document-free workflows

Set document.enabled to false to run a selfie-only flow — for example a low-friction KYC level 1 that collects the applicant’s name and a liveness-checked selfie with no ID document:

1
{
2
  "data_requirements": {
3
    "selfie": true,
4
    "document": { "enabled": false, "accepted_types": [] },
5
    "user_info": {
6
      "enabled": true,
7
      "fields": ["first_name", "last_name"],
8
      "required_fields": ["first_name", "last_name"]
9
    }
10
  }
11
}

Rules for document-free workflows:

• selfie must be true — a workflow has to capture at least one artifact.
• The graph cannot contain document-dependent policies (document scan, face match, age verification, watchlist screening, and others that read document data). The policies endpoint marks these with requires_document: true, and creating or updating a workflow that combines them with document.enabled: false returns a validation error.
• The capture flow skips all document steps and goes straight from personal information to the selfie and liveness check.
• Billing still follows pay-on-capture-success: one IDV is billed when a session whose selfie passed the capture liveness gate begins processing.
• Selfie-compatible checks still work — in particular Duplicate Face Detection (face_duplicate), which flags a session when the same face has already verified under a different external_ref in your organization. Matches route to manual review by default; sessions that share the session’s external_ref (the same account re-verifying) or have no external_ref never flag.

Returning-user re-verification

A returning-user re-verification confirms that the person in front of the camera is the same person you already verified — a step-up check before a sensitive action such as a large withdrawal, a password reset, a device change, or a high-value transaction. Instead of re-running full onboarding, the returning user takes a single liveness-checked selfie, and the platform compares it against that person’s previously verified facial records to pass or fail the session.

This is a specialised document-free workflow: it captures a selfie only, with no ID document. The comparison is one-to-one — the new selfie against the one known person — which is the opposite of Duplicate Face Detection, where a selfie is searched one-to-many against everyone in your organization.

Setting it up

Add the Returning User Face Verification (face_reauth) policy to a document-free workflow, or start from the Returning User Re-Verification template, which ships a ready-made graph:

1
{
2
  "reauth": {
3
    "type": "policy",
4
    "policy": "face_reauth",
5
    "config": {
6
      "sensitivity": "balanced",
7
      "failure_action": "manual_review",
8
      "on_missing_enrollment": "manual_review"
9
    },
10
    "on_pass": "auto_decision",
11
    "on_fail": "review"
12
  }
13
}

The workflow must be document-free (document.enabled: false, selfie: true). The Returning User Face Verification policy is available on the Starter plan and above.

external_ref is required

When you create the session, external_ref must be set to the identifier of the person you want to re-verify — the same external_ref used when that person was originally verified. The policy uses it to look up whose facial records to compare against.

Because this is an authentication check rather than a fraud screen, it fails closed:

• A session created with no external_ref fails and routes to review.
• A session whose external_ref doesn’t match anyone you’ve verified fails and routes to review.

Configuration

Result and identity status

The pass/fail outcome rides the normal session result — there is no separate event or billing SKU; a re-verification session is billed like any other verification. A failed re-verification never changes the person’s verified status: the result lives on the session, and the verified identity stays verified. You decide what to do with the outcome — block the sensitive action, require a fallback, or send it to your own review queue — by gating on the session result.

Rollout percentage

Deploy workflow changes gradually with percentage-based rollout:

1
{
2
  "rollout_percentage": 25
3
}

25% of new sessions will use this workflow version; the remaining 75% continue using the previous version. The routing is deterministic per session ID, so the same session always gets the same version.

Default workflows

Each organization has one default workflow per environment (sandbox and live). When a session is created without a workflow_id, the default workflow is used.

Workflow API

Create a workflow

$
curl -X POST https://api.withverifa.com/api/v1/workflows \
>
  -H "X-API-Key: vk_live_your_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Standard KYC",
>
    "description": "Document + face match + AML screening",
>
    "graph": { ... }
>
  }'

List workflows

$
curl https://api.withverifa.com/api/v1/workflows \
>
  -H "X-API-Key: vk_live_your_key_here"

Publish a workflow

$
curl -X POST https://api.withverifa.com/api/v1/workflows/workflow_abc123/publish \
>
  -H "X-API-Key: vk_live_your_key_here"

Set as default

$
curl -X POST https://api.withverifa.com/api/v1/workflows/workflow_abc123/set-default \
>
  -H "X-API-Key: vk_live_your_key_here"

Validation

The workflow engine validates graphs before publishing:

• All nodes referenced in routing must exist
• The entry node must exist and be a start node
• Policy nodes must have on_pass and on_fail routes
• Conditional nodes must have at least one route with a default fallback
• No cycles (the graph must be a DAG)
• No duplicate policies (unless explicitly allowed)
• Every path must reach a terminal node

Invalid workflows cannot be published.

Related

• Verifications & Checks — Available check types for workflow nodes
• Sessions — How sessions trigger workflow execution
• Cases — What happens when a workflow routes to needs_review