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

Overview

Workflow API

Credentials API

Document API

Identity API (Legacy)

Workflow API Overview

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

Executing a Workflow

Credentials API

Fintech Company Using Beltic

​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

Executing a Workflow

Credentials API

Fintech Company Using Beltic

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