OpenAPI · REST reference

REST request envelopes, authentication, workflow lifecycle, error handling, configuration and file upload.

Getting Started

Base URL

Request Format

POST {base_url}?api={apiName}&apiVersion={apiVersion}&apiKey={apiKey}&sign={sign}
Content-Type: application/json
x-domain: {domainId}

{JSON body}

Submit a Workflow

Endpoint: workflow.apply.submit POST

Routes to the currently published (PUBLISHED) workflow by eventType + source and starts an execution.

apiVersion

Request

{
  "eventType": "KYC_EVENT",
  "source": "API",
  "data": {
    "customerId": "demo-customer-001",
    "fullName": "ZHANG SAN",
    "dateOfBirth": "1990-01-01",
    "nationality": "CN"
  },
  "workflowId": ""
}

Response

{
  "apiCode": 200,
  "apiMsg": "OK",
  "data": {
    "code": 200,
    "message": null,
    "executionId": "exec-7208f03b931e4897",
    "status": "EXECUTING",
    "requestId": "...",
    "sync": false
  }
}

Where to find the Workflow ID: in WIDTH One Platform, open Workflow. Copy the Workflow ID shown beside the workflow name in the listing and pass it as workflowId when using apiVersion 2.0.0.

Response Format

Success:

{
  "apiCode": 200,
  "apiMsg": "OK",
  "data": {}
}

Error:

{
  "apiCode": 999001,
  "apiMsg": "SIGN_ERROR",
  "data": null
}

Read the response in order: HTTP status, then apiCode, then data.code and data.data where the endpoint uses a business envelope. apiCode 200 alone does not prove business success; use the endpoint-specific business result.

Error Codes

Authentication

Signature Computation

sign = HmacSHA256(apiSecret, requestBody)

Both key and body use UTF-8 encoding. The result is a 64-character lowercase hex string. The signature must be computed on the exact bytes sent as the HTTP body.

Code Examples

Java:

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(apiSecret.getBytes("UTF-8"), "HmacSHA256"));
byte[] hash = mac.doFinal(requestBody.getBytes("UTF-8"));
String sign = HexFormat.of().formatHex(hash); // Java 17+

Python:

import hmac, hashlib

sign = hmac.new(
    api_secret.encode('utf-8'),
    request_body.encode('utf-8'),
    hashlib.sha256
).hexdigest()

Node.js:

const crypto = require('crypto');
const sign = crypto.createHmac('sha256', apiSecret)
    .update(requestBody, 'utf8').digest('hex');

Idempotency

All node data submission APIs are idempotent based on callbackKey. Submitting the same callbackKey multiple times is safe — only the first successful submission takes effect. This allows safe retries on network timeouts.

Interaction Model

• Client-Side (App/Web): Chain-Driven Flow. Your frontend is driven by the nextStep object returned in each submission response. No global polling required. Only poll dedicated .data endpoints for async tasks like OCR.
• Server-Side (Tenant Backend): Final Status Polling. After the last user-input node, poll workflow.execution.status at relaxed intervals (1–5 min) until terminal state.

Workflow Lifecycle API

The Workflow Lifecycle API is the pure server-side integration path: your backend submits an event, polls for the execution status and the Case decision, and — when a request is lost or retried — queries whether the customer already has an execution in flight. Three endpoints form one closed loop.

This differs from the node-driven SDK path documented under KYC / KYB, where the client submits data node by node. Here the platform runs the entire published workflow end to end and you only submit and poll.

Flow Overview

1. Submit
2. Poll Status
3. Case Decision

workflow.apply.query sits before this loop as a recovery path: call it when a submit may have already happened (timeout or upstream retry) to avoid submitting twice.

Billing

Status & Case Decision

Endpoint: workflow.execution.status POST

Read-only — it does not trigger execution and is not billed. executionId is checked against your tenant (and x-domain); it cannot be queried across tenants. Use apiVersion 1.0.0.

Request

{ "executionId": "exec-7208f03b931e4897" }

Response

{
  "apiCode": 200,
  "apiMsg": "OK",
  "data": {
    "executionId": "exec-7208f03b931e4897",
    "status": "COMPLETED",
    "caseNo": "C001443",
    "caseStatus": "REJECTED",
    "riskScore": 45.0,
    "resolvedAt": 1784714818000
  }
}

Status Semantics

Response by Stage

Stage 1 — automatic nodes running, no Case yet (the brief window before the decision node):

{ "apiCode": 200, "apiMsg": "OK",
  "data": { "executionId": "exec-xxxx", "status": "RUNNING" } }

No caseStatus field → no Case generated yet, keep polling.

Stage 2 — Case generated, awaiting manual handling:

{ "apiCode": 200, "apiMsg": "OK",
  "data": { "executionId": "exec-xxxx", "status": "RUNNING",
            "caseNo": "C001286", "caseStatus": "UNASSIGNED", "riskScore": 49.17 } }

While being handled manually, caseStatus reflects progress: UNASSIGNED (queued) → UNDER_REVIEW (after a reviewer picks it up); RETURNED when sent back for rework.

Stage 3 — decision reached (manual review or automatic decision):

{ "apiCode": 200, "apiMsg": "OK",
  "data": { "executionId": "exec-xxxx", "status": "COMPLETED",
            "caseNo": "C001443", "caseStatus": "REJECTED", "riskScore": 45.0,
            "resolvedAt": 1784714818000 } }

Polling Exit Conditions

Every execution generates a Case once it reaches the decision node (manual review → UNASSIGNED / UNDER_REVIEW; automatic pass/reject/close → a terminal Case directly), so:

caseStatus in {APPROVED, REJECTED, CLOSED}
OR status == FAILED
OR status == CONFIRMED_CANCELLATION_ENUM

Recovery Query (Dedup & Resume)

Endpoint: workflow.apply.query POST

Looks up whether a customer already has an execution by eventType + source + customerId. Read-only — it starts no new execution and is not billed. Use apiVersion 1.0.0.

• Resume after a break — if submit timed out or the process crashed before you got an executionId: query first; on a hit, recover the executionId and resume polling, avoiding a duplicate (billed) submit.
• Deduplicate submits — when an upstream retry may re-fire for the same customer: skip submit if the query returns RUNNING / APPROVED.

Request

{
  "eventType": "KYC_EVENT",
  "source": "API",
  "customerId": "demo-customer-001"
}

Response

{
  "apiCode": 200,
  "apiMsg": "OK",
  "data": {
    "code": 200,
    "executionId": "exec-7208f03b931e4897",
    "status": "RUNNING"
  }
}

Error Codes

Code Example

curl (full loop)

API_KEY="ak_xxx"
API_SECRET="sk_xxx"
DOMAIN_ID="{domainId}"
BASE_URL="https://api-gateway-platform.width.com/gateway"

# HMAC-SHA256 sign helper / 签名助手
sign() { printf "%s" "$1" | openssl dgst -sha256 -mac HMAC -macopt key:"$API_SECRET" | sed 's/^.* //'; }

# 0. (optional) recovery query — dedup before submit / 恢复查询防重
BODY='{"eventType":"KYC_EVENT","source":"API","customerId":"demo-customer-001"}'
curl -s -X POST "${BASE_URL}?api=workflow.apply.query&apiVersion=1.0.0&apiKey=${API_KEY}&sign=$(sign "$BODY")" \
  -H "Content-Type: application/json" -H "x-domain: ${DOMAIN_ID}" -d "$BODY"

# 1. submit / 发起工作流
BODY='{"eventType":"KYC_EVENT","source":"API","data":{"customerId":"demo-customer-001","fullName":"ZHANG SAN"},"workflowId":""}'
curl -s -X POST "${BASE_URL}?api=workflow.apply.submit&apiVersion=2.0.0&apiKey=${API_KEY}&sign=$(sign "$BODY")" \
  -H "Content-Type: application/json" -H "x-domain: ${DOMAIN_ID}" -d "$BODY"
# -> record data.executionId / 记下 data.executionId

# 2. poll status / 轮询执行状态
BODY='{"executionId":"exec-7208f03b931e4897"}'
curl -s -X POST "${BASE_URL}?api=workflow.execution.status&apiVersion=1.0.0&apiKey=${API_KEY}&sign=$(sign "$BODY")" \
  -H "Content-Type: application/json" -H "x-domain: ${DOMAIN_ID}" -d "$BODY"

Python (polling loop)

import hashlib, hmac, json, os, time, requests

GATEWAY = "https://api-gateway-platform.width.com/gateway"
API_KEY = os.environ["WIDTH_API_KEY"]
API_SECRET = os.environ["WIDTH_API_SECRET"]
DOMAIN_ID = os.environ["WIDTH_DOMAIN_ID"]
# Supply only the cancellation enum verified by WIDTH engineering.
# Do not guess between the conflicting spellings in the reference.
CANCELLED_STATUS = os.environ["WIDTH_CONFIRMED_CANCEL_STATUS"]

def call(api, version, payload):
    body = json.dumps(payload, separators=(",", ":"))
    signature = hmac.new(API_SECRET.encode(), body.encode(), hashlib.sha256).hexdigest()
    response = requests.post(GATEWAY,
        params={"api": api, "apiVersion": version, "apiKey": API_KEY, "sign": signature},
        headers={"Content-Type": "application/json", "x-domain": DOMAIN_ID},
        data=body, timeout=30)
    response.raise_for_status()
    result = response.json()
    if result.get("apiCode") != 200:
        raise RuntimeError(result)
    data = result.get("data")
    if isinstance(data, dict) and data.get("code", 200) != 200:
        raise RuntimeError(data)
    return data

identity = {"eventType": "KYC_EVENT", "source": "API", "customerId": "demo-customer-001"}
recovered = call("workflow.apply.query", "1.0.0", identity)
if recovered and recovered.get("status") == "APPROVED":
    print(recovered)
else:
    if recovered and recovered.get("status") == "RUNNING":
        execution_id = recovered["executionId"]
    else:
        submitted = call("workflow.apply.submit", "2.0.0", {
            "eventType": identity["eventType"], "source": identity["source"],
            "data": {"customerId": identity["customerId"], "fullName": "ZHANG SAN"},
            "workflowId": ""})
        execution_id = submitted["executionId"]
        # Persist execution_id before polling; recover after an interrupted submit.
    while True:
        state = call("workflow.execution.status", "1.0.0", {"executionId": execution_id})
        if not isinstance(state, dict):
            raise RuntimeError("Verify executionId, apiKey and x-domain; no execution returned")
        if state.get("caseStatus") in ("APPROVED", "REJECTED", "CLOSED") or state.get("status") in ("FAILED", CANCELLED_STATUS):
            print(state)
            break
        time.sleep(30 if state.get("caseStatus") in ("UNASSIGNED", "UNDER_REVIEW", "RETURNED") else 5)

FAQ

Configuration

Retrieve platform configuration data (country lists, document types, form templates, etc.) before starting a workflow.

Endpoint: prepare.avira.config POST

{
  "keys": "particular,avira_ssic,avira_ssoc,avira_countries,avira_document_master,avira_document_default_rule,required-form,avira_phone_code,avira_entity_types,ownership_structure_layer,transaction_behaviour,product_service_complexity,source_of_wealth,avira_source_of_funds"
}

Configuration Keys

File Upload

For any API requiring S3 URIs (documents, photos), upload files first.

Step 1 — Get Upload Token

Endpoint: storage.upload.token POST

Request body: {}. Token is valid for 15 minutes.

Response:

{
  "apiCode": 200,
  "data": {
    "uploadToken": "a1b2c3d4e5f6...",
    "expiresIn": 900
  }
}

Step 2 — Upload File

Storage Service URL:

Multipart upload:

curl -X POST "${STORAGE_URL}/api/v1/upload/file" \
  -F "uploadToken=a1b2c3d4e5f6..." \
  -F "file=@passport_front.jpg"

Base64 upload:

curl -X POST "${STORAGE_URL}/api/v1/upload" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadToken": "a1b2c3d4e5f6...",
    "image": "data:image/jpeg;base64,/9j/4AAQ...",
    "filename": "passport_front.jpg"
  }'

Response:

{
  "apiCode": 200,
  "data": {
    "url": "s3://workflow-kyc/tenantImages/2026-04-16/abc123.jpg",
    "filename": "passport_front.jpg",
    "content_type": "image/jpeg",
    "size": 245760
  }
}

Error handling & retry strategy