Build workflows with the API

A workflow can be built without the dashboard, for example by an AI assistant that turns "check that people are 18 or older" into steps. The calls need an API key with the workflows:write scope (in Settings under API keys, permission Manage workflows). It is never preselected, and keys made before scopes existed do not have it. The key's environment decides the workflow's: a sandbox key builds sandbox workflows and cannot see production ones.

  • GET /v1/workflows/catalog: every step with its price in CHF, options and dependencies, the settings a workflow takes (minimum age, IP countries, outcome overrides with their reason codes, score thresholds, status rules, four eyes, document rules) and the countries and documents of the key's environment. It comes from the rules the server checks, so a definition built from it validates.
  • POST /v1/workflows: creates a draft. The response has price_per_verification_chf and warnings, hints on a valid definition that is probably not what was meant.
  • GET /v1/workflows/{id} and GET /v1/workflows?status=draft|published|all: full definitions, drafts included. Without status the list stays the short list of published, active workflows.
  • PATCH /v1/workflows/{id}: changes the fields sent. A draft stays a draft. A published workflow stays published and the change applies to new verifications at once, as a save in the dashboard does; the response says so with live: true. Verifications already started keep the definition they started with. The environment cannot change.
  • POST /v1/workflows/{id}/publish: makes it the workflow new verifications run, with the dashboard's checks: the definition, documents the environment offers, the FINMA profile and the plan's production workflow slots.
  • There is no DELETE: PATCH with active: false takes a workflow out of use and can be undone. Remove workflows in the dashboard.
curl
curl -X POST https://api-verify.secuveri.com/v1/workflows \
  -H "x-api-key: $SECUVERI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Age check 18+","steps":["liveness-check","age-estimation","identity-document","face-match"],"minimum_age":18}'
JSON
{
  "workflow": {
    "id": "<workflow id>",
    "name": "Age check 18+",
    "environment": "sandbox",
    "status": "draft",
    "active": true,
    "minimum_age": 18,
    "steps": [
      "liveness-check",
      "age-estimation",
      "identity-document",
      "face-match"
    ],
    "price_per_verification_chf": 0.78
  },
  "warnings": [],
  "live": false
}

Fields are snake_case: name, description, steps (in the order the person sees them), step_configs (only options that differ from their default), minimum_age, ip_countries, outcome_overrides, score_thresholds, status_rules, four_eyes, document_rules, and active on PATCH. An unknown field is refused, so a typo is not dropped silently. An invalid definition answers 400 with every problem in message and one by one in errors.

StatusMeaning
400Invalid definition or unknown field; errors lists the problems
402Plan limit (code: plan_required): no free production workflow slot, or the FINMA profile is not in the plan
403The key lacks the scope, names another environment, or a partner app's connection lacks the setup right
404No workflow with this id among the key's environment's workflows
409The workflow cannot be published as it is (for example a document its environment does not offer)
429More than 120 calls, or 30 changes, in a minute

Every create, change and publish is recorded in the organization's audit log with the key as actor (api_key:<id>). Publishing and changing a published workflow change which checks real verifications go through, so an assistant should confirm them with the person responsible first. A partner app (Connect with secuveri) needs the workflows:write setup right for all of this, publishing included.