> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawapass.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verification workflows

> Define the checks a user must complete using a verification workflow

## 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](https://backoffice.pawapass.com/settings/workflows), 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](https://backoffice.pawapass.com/settings/verification-markets) in backoffice.
* **By ID.** Pass a `workflowId` to run a specific workflow. This is the 8-character workflow shortId shown in [backoffice](https://backoffice.pawapass.com/settings/workflows).

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](#reading-the-workflow-back)).

## Checks a workflow can include

<AccordionGroup>
  <Accordion title="Face scan" icon="face-viewfinder">
    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.
  </Accordion>

  <Accordion title="Document scan" icon="id-card">
    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.
  </Accordion>
</AccordionGroup>

## Selecting a workflow

<Tabs>
  <Tab title="By country default">
    Omit `workflowId`. pawaPass runs the default workflow configured for the `country`, so most integrations never send a workflow at all.

    ```json theme={null}
    {
      "externalId": "user-zm-98765",
      "country": "ZM",
      "successUrl": "https://your-website.com/success",
      "errorUrl": "https://your-website.com/error",
      "supportUrl": "https://your-website.com/support"
    }
    ```
  </Tab>

  <Tab title="By workflow ID">
    Pass the 8-character `workflowId` from [backoffice](https://backoffice.pawapass.com/settings/workflows) to run a specific workflow, for example a liveness-only check that skips the document scan.

    ```json theme={null}
    {
      "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.
  </Tab>
</Tabs>

## Reading the workflow back

The verification response and every webhook include the resolved `workflowId`:

```json theme={null}
{
  "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.

<Note>
  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](/verification-requirements).
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.