Workflow API Overview

What is the Workflow API?

The Workflow API is the execution plane that orchestrates everything Beltic does — document verification, identity checks, sanctions screening, business lookups, and credential issuance — into a single callable process. Instead of manually sequencing eight API calls (create account → create session → upload document → run verification → check screening → issue credential), you configure a workflow once and call POST /v1/workflows/execute. The workflow runs the blocks in order and returns the output, including any signed credentials, in a single response.

curl -X POST https://api.beltic.com/v1/workflows/execute \
  -H "X-Api-Key: $BELTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "wf_kyc_standard",
    "options": {
      "input": {
        "subject_id": "user_jane_doe_001",
        "document_type": "passport"
      }
    }
  }'

How Workflows Are Structured

A workflow is a state graph of blocks — discrete units of work that run in sequence or in parallel. Each block type wraps a specific Beltic capability:

Block type	What it does
`document_verification`	Extracts and verifies a government-issued ID or proof of address
`business_lookup`	Looks up company registration data by name or registration number
`sanctions_screening`	Runs the subject against global sanctions, PEP, and adverse media lists
`identity_verification`	Runs liveness and document-match checks
`credential_issue`	Issues a signed JWT-VC credential from the verified data — this is typically the final block

The credential block is what turns a verification outcome into a portable, cryptographic artifact. The signed credential the workflow emits can be stored, forwarded to partners, and verified at every future transaction point — without re-running the workflow.

Synchronous vs Paused Executions

Workflow execution is synchronous by default. The HTTP response tells you the outcome:

Status	HTTP code	Meaning
`completed`	`200`	Workflow ran to completion. Output contains the credential.
`failed`	`200`	Workflow ran but a block failed (e.g. document rejected). Check `output` for details.
`paused`	`202`	Workflow paused — awaiting external input (e.g. manual review at a sponsor bank). Resume when input is available.
`cancelled`	`200`	Workflow was cancelled mid-run.

The 202 Pause Flow

Some verification steps can’t be resolved automatically — a policy mismatch may require a manual review from a compliance officer or a sponsor bank before a credential can be issued. When this happens, the workflow pauses and returns 202 with a pausePoints array describing what input is needed to continue.

{
  "success": false,
  "status": "paused",
  "executionId": "exec_01HQ...",
  "pausePoints": [
    {
      "blockId": "sponsor_bank_review",
      "reason": "policy_mismatch",
      "requiredInput": ["approval_reference", "reviewer_id"]
    }
  ]
}

Once the external review completes, resume the execution by re-running with the runFromBlock parameter pointing to the block after the pause.

Execution Output

Every completed execution returns an output object keyed by block ID:

{
  "success": true,
  "status": "completed",
  "executionId": "exec_01HQ7P...",
  "output": {
    "document_verification": {
      "status": "passed",
      "document_type": "passport",
      "name": { "first": "Jane", "last": "Doe" },
      "birth_date": "1990-05-15"
    },
    "sanctions_screening": {
      "status": "clear"
    },
    "credential_issue": {
      "credential_id": "cred_01HQ...",
      "credential_type": "user",
      "signed_payload": "eyJhbGciOiJFUzI1NiIs...",
      "status": "active",
      "expires_at": "2026-08-19T10:30:00Z"
    }
  }
}

The signed_payload in the credential block output is the JWT-VC. Store it — it’s the artifact your downstream services verify against.

Configuring a Workflow

Workflows are configured in the Beltic Console using a visual block editor. You add blocks, connect them in order, configure each block’s inputs and conditions, and deploy — similar to how you’d configure a CI/CD pipeline, but for verification logic. What happens at deploy time: Beltic validates the workflow graph, assigns a stable workflowId (e.g. wf_kyc_standard), and creates an immutable deployed version. The deployed version is what POST /v1/workflows/execute runs by default. Earlier versions are preserved and can still be targeted via the executions API for debugging. Draft vs deployed: While editing, the workflow is in draft state. You can test draft workflows by passing "useDraftState": true to POST /v1/workflows/execute — useful for staging validation before promoting a change to production. Code-defined workflows (declarative YAML/JSON config and Git-based deployment) are on the roadmap. The REST API for workflow execution is already stable and versioned — switching from Console-deployed to code-defined workflows will not require changes to your integration.

Workflows vs Direct API Calls

The Workflow API supersedes the Identity API for most use cases. The direct comparison:

	Identity API (legacy)	Workflow API
Number of API calls	5–8 per verification	1
Credential issuance	Manual, separate call	Built into the workflow
Pause / resume	Not supported	Native
Audit trail	Partial	Full, per-block
Subworkflows	No	Yes

The Identity API remains available for existing integrations but is not recommended for new builds.

Where to Next

Executing a Workflow

Walk through POST /v1/workflows/execute — inputs, outputs, pause handling, and partial re-runs

Credentials API

Understand the signed credential that workflows emit — and how to verify it at transaction time

Fintech Company Using Beltic

See workflows and credentials working together — from user onboarding through transaction authorization

Documentation Index

​What is the Workflow API?

​How Workflows Are Structured

​Synchronous vs Paused Executions

​The 202 Pause Flow

​Execution Output

​Configuring a Workflow

​Workflows vs Direct API Calls

​Where to Next