Verification workflows

Overview

A workflow defines the checks a user must complete: a biometric face scan, scanning an identity document, and any other steps your account is configured for. You set up workflows in the pawaPass backoffice, and every verification runs one. You do not send the list of checks on each request. When you create a verification, pawaPass resolves the workflow to run, and the workflow decides the checks. You choose the workflow in one of two ways:

By country (default). Omit workflowId and pawaPass runs the default workflow configured for the verification’s country. You set the per-country defaults under verification markets in backoffice.
By ID. Pass a workflowId to run a specific workflow. This is the 8-character workflow shortId shown in backoffice.

The resolved workflow’s workflowId is returned on the verification and on every webhook, so you can tell which workflow ran. It can be null in some cases (see Reading the workflow back).

Checks a workflow can include

Face scan

The user completes a biometric face scan with liveness detection. When the workflow also includes a document scan, the live face is compared against the document photo.

Document scan

The user scans an identity document (passport, national ID, driver license, voter card, refugee card, or residence permit). The extracted data is returned in the identityDocument field once the verification is approved.

Selecting a workflow

By country default
By workflow ID

Omit workflowId. pawaPass runs the default workflow configured for the country, so most integrations never send a workflow at all.

{
  "externalId": "user-zm-98765",
  "country": "ZM",
  "successUrl": "https://your-website.com/success",
  "errorUrl": "https://your-website.com/error",
  "supportUrl": "https://your-website.com/support"
}

Pass the 8-character workflowId from backoffice to run a specific workflow, for example a liveness-only check that skips the document scan.

{
  "externalId": "user-zm-98765",
  "country": "ZM",
  "workflowId": "aB1cD2eF",
  "successUrl": "https://your-website.com/success",
  "errorUrl": "https://your-website.com/error",
  "supportUrl": "https://your-website.com/support"
}

A workflowId that does not resolve to one of your workflows returns 404 with code VERIFICATION_WORKFLOW_NOT_FOUND. A workflow that cannot run in the verification’s country, for example one that uses a check not available there, returns 409 with code WORKFLOW_CONFIG_INCOMPATIBLE. In both cases the verification is not created.

Reading the workflow back

The verification response and every webhook include the resolved workflowId:

{
  "id": "aB1cD2eF",
  "workflowId": "wf3kD9aB",
  "status": "STARTED",
  "requirements": [
    { "type": "FACE_SCAN" },
    { "type": "DOCUMENT_SCAN" }
  ]
}

workflowId is the id of the workflow that ran the verification, when it is known. It can be null in two situations:

Before it is pinned. A verification created with neither workflowId nor requirements runs on the country default and is pinned when it starts, so workflowId is null while it is still CREATED (unstarted) and fills in from STARTED onward. Sending workflowId or requirements on create pins it right away.
On older verifications. Records that predate pawaPass storing workflowId, or predate workflows entirely, report null whatever their status.

When workflowId is null, read the requirements array on the response to see the checks the verification runs. Before the verification is pinned, the array can still change when it starts, if the country default was reassigned since create. Read it from STARTED onward for the checks that run.

Older integrations set the checks by sending a requirements array on create. That still works, but a workflow runs either way: the resolved workflow decides the checks, and the array no longer overrides it. Sending it is no longer the recommended way to configure checks. See Verification requirements.

Get Started

Guides

Verification workflows

Overview

Checks a workflow can include

Selecting a workflow

Reading the workflow back

​Overview

​Checks a workflow can include

​Selecting a workflow

​Reading the workflow back

Overview

Checks a workflow can include

Selecting a workflow

Reading the workflow back