Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.beltic.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

POST /v1/workflows/execute runs a workflow and returns the result. By default it uses the latest deployed version of the workflow. The call is synchronous — it holds the connection until the workflow reaches a terminal state or pauses. Typical execution times:
Workflow typeP50P95
KYC (document + liveness)2.5s6s
KYB (business lookup + sanctions)1.8s4s
Sanctions screening only400ms900ms
Credential issuance only120ms300ms
These are end-to-end wall-clock times under normal load. Design your UX accordingly — KYC flows warrant a loading state; credential-only calls are fast enough to be invisible.

​
Prerequisites

​
Basic Execution

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"
      }
    }
  }'

​
Request Fields

FieldTypeRequiredDescription
workflowIdstringYesID of the deployed workflow to run
options.inputobjectNoInput data passed to the first block
options.environmentVariablesobjectNoOverride environment variables for this run
options.workflowVariablesobjectNoOverride workflow-level variables
options.maxParallelNodesnumberNoCap parallel block execution (default: 2)
useDraftStatebooleanNoRun the draft workflow state instead of deployed

​
Handling the Response

​
200 — Terminal (Completed or Failed)

The workflow ran to a terminal state. Check success and status to determine outcome: 
{
  "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",
      "nationality": "US"
    },
    "sanctions_screening": {
      "status": "clear"
    },
    "credential_issue": {
      "credential_id": "cred_01HQ...",
      "credential_type": "user",
      "signed_payload": "eyJhbGciOiJFUzI1NiIs...",
      "status": "active",
      "issued_at": "2026-05-21T10:30:00Z",
      "expires_at": "2026-08-19T10:30:00Z"
    }
  }
}
If a block failed, success will be false and error will describe what went wrong: 
{
  "success": false,
  "status": "failed",
  "executionId": "exec_01HQ7Q...",
  "error": "document_verification: document expired",
  "output": {
    "document_verification": {
      "status": "failed",
      "reason": "optical_expiry"
    }
  }
}

​
202 — Paused

The workflow reached a block that requires external input before it can continue — a manual compliance review, sponsor bank approval, or a human-in-the-loop decision: 
{
  "success": false,
  "status": "paused",
  "executionId": "exec_01HQ7R...",
  "pausePoints": [
    {
      "blockId": "sponsor_bank_review",
      "reason": "policy_mismatch",
      "description": "Subject's jurisdiction requires sponsor bank sign-off",
      "requiredInput": ["approval_reference", "reviewer_id"]
    }
  ]
}
Store the executionId. When the external review is complete, resume by running POST /v1/workflows/execute again with runFromBlock pointing to the block after the pause point.

​
Resuming a Paused Execution

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",
    "runFromBlock": {
      "executionId": "exec_01HQ7R...",
      "startBlockId": "credential_issue"
    },
    "options": {
      "input": {
        "approval_reference": "BANK-2026-00412",
        "reviewer_id": "rev_jones"
      }
    }
  }'
The resumed execution picks up state from exec_01HQ7R... and runs from credential_issue forward, skipping the already-completed blocks.

​
Listing Past Executions

Check the history of any workflow: 
curl "https://api.beltic.com/v1/workflows/wf_kyc_standard/executions" \
  -H "X-Api-Key: $BELTIC_API_KEY"

[
  {
    "executionId": "exec_01HQ7P...",
    "status": "completed",
    "updatedAt": "2026-05-21T10:30:10Z"
  },
  {
    "executionId": "exec_01HQ7R...",
    "status": "paused",
    "updatedAt": "2026-05-21T09:15:02Z"
  }
]

​
Testing with Draft State

Before deploying a workflow change, run it against draft state to validate the changes: 
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",
    "useDraftState": true,
    "options": { "input": { "subject_id": "test_user_001" } }
  }'
Never run draft state in production. Use a staging API key (sk_staging_*) when testing draft workflows.

​
Error Codes

HTTPMeaning
400Request body failed validation
401API key missing or invalid
403API key lacks execution permissions
404Workflow ID not found or not deployed
409Execution ID conflict (duplicate idempotency key)
422Workflow is valid but semantically unexecutable (e.g. runFromBlock references unknown block)

​
Next Steps

Credentials API

Deep-dive into the credential that workflows emit

Verifying a Credential

How to verify the signed credential at transaction time

Fintech Company Using Beltic

Full end-to-end example — workflow execution, sponsor bank queue, and transaction authorization