For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • Getting Started
    • Introduction
    • How Verifa Works
    • Quickstart
    • Choosing an Integration Method
  • Use Cases
    • KYC Onboarding
    • Age Verification
    • AML Compliance
    • Fraud Prevention
    • Marketplace Trust & Safety
  • Core Concepts
    • Overview
    • Sessions
    • Verifications & Checks
    • Workflows
    • Identities
    • Cases
    • Screening & Reports
    • Lists
  • Integration Guides
    • Overview
    • JavaScript SDK
    • Web Capture Flow
    • API-Only Integration
    • Mobile SDK
    • Webhooks Guide
    • MCP Server
    • Migrating from Persona
  • API Details
    • Overview
    • Authentication
    • Pagination
    • Rate Limiting
    • Versioning
    • Errors
    • Webhooks
    • Idempotency
    • Key Inflection
    • Data Access
    • Data Retention
  • Tutorials
    • Creating Your First Verification Session
    • Creating a Workflow
    • Receiving Webhooks & Validating Signatures
    • Handling Webhook Events
    • Custom Document Types & AI Extraction
  • Best Practices
    • Testing
    • Preventing Duplicates
    • Fraud Signals
    • Changelog
  • API Reference
      • GETList workflows
      • POSTCreate a workflow
      • GETGet a workflow
      • PATCHUpdate a workflow
      • POSTTrigger a workflow
      • GETGet session workflow run
      • GETList available verification policies
      • GETList workflow versions
      • GETGet workflow analytics
      • POSTSet a workflow as default
      • POSTDeactivate a workflow
      • GETList workflow drafts
      • GETGet a workflow draft
      • GETDiff a draft against the current workflow
      • POSTDry-run a workflow draft
      • POSTPublish a workflow draft
      • POSTDry-run a workflow
      • GETGet workflow rollout map
      • PUTUpdate workflow rollout map
      • POSTClone a workflow
      • GETList verification policies
API ReferenceWorkflows

Create a workflow

POST
https://devapi.withverifa.com/api/v1/workflows
POST
/api/v1/workflows
$curl -X POST https://devapi.withverifa.com/api/v1/workflows \
>     -H "X-API-Key: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "name": "string",
>  "steps": [
>    {}
>  ]
>}'
1{
2  "id": "wfl_abc123",
3  "name": "Standard KYC",
4  "version": 3,
5  "steps": [
6    {
7      "policy": "document_ocr",
8      "label": "Document OCR",
9      "config": {},
10      "on_fail": "review",
11      "on_pass": null,
12      "on_error": "review"
13    }
14  ],
15  "is_default": true,
16  "is_active": true,
17  "created_at": "2024-01-15T09:30:00Z",
18  "description": "string",
19  "step_count": 4,
20  "updated_at": "2024-01-15T09:30:00Z",
21  "data_requirements": {},
22  "format": "steps",
23  "graph": {},
24  "purpose": "general_kyc",
25  "compliance_level": "ial2"
26}
Creates a new verification workflow with the specified steps.
Was this page helpful?
Previous

Get a workflow

Next
Built with

Authentication

X-API-Keystring

Organization API key. Keys are prefixed with vk_live_ (production) or vk_sandbox_ (sandbox).

Headers

Verifa-VersiondateOptional

API version date string (e.g. 2026-02-01). If omitted, the version pinned to your API key is used.

Key-InflectionenumOptionalDefaults to snake

Response key casing. Defaults to snake.

Allowed values:

Request

This endpoint expects an object.
namestringRequired
stepslist of maps from strings to anyRequired
descriptionstring or nullOptional
is_defaultbooleanOptionalDefaults to false
data_requirementsmap from strings to any or nullOptional
screening_settingsmap from strings to any or nullOptional
graph_layoutmap from strings to any or nullOptional
purposeenumOptional

Declares what the workflow is used for. Downstream checks like consortium matching use this to score cross-org matches contextually. For example, the same face at two schools is normal for enrollment but suspicious for financial aid.

compliance_levelenumOptional

Compliance standard to enforce on this workflow. When set to “ial2”, the workflow must include document_ocr, face_match, proof of address, OTP verification, and user info with name fields per NIST SP 800-63-3.

Allowed values:

Response

Workflow created.
idstring
namestring
versioninteger
stepslist of objects
Ordered list of workflow steps.
is_defaultboolean
is_activeboolean
created_atdatetime
descriptionstring or null
step_countinteger
Number of steps in the workflow.
updated_atdatetime
data_requirementsmap from strings to any or null
Data requirements configuration for this workflow.
formatenumDefaults to steps

Workflow format — “steps” for legacy array format, “graph” for DAG format.

Allowed values:
graphmap from strings to any or null

DAG graph representation of the workflow. Present when format is “graph”. Contains “nodes” (dict of node objects) and “entry” (start node ID).

purposeenum

What the workflow is used for. Used by consortium matching to apply purpose-aware scoring — e.g., financial aid matches are scored higher than enrollment matches.

compliance_levelenum

Compliance standard enforced on this workflow. “ial2” enforces NIST SP 800-63-3 identity proofing requirements.

Allowed values:

Errors

401
Unauthorized Error
422
Unprocessable Entity Error