# 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.

```shell
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}'
```

```shell
{
  "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`.

| Status | Meaning |
| --- | --- |
| 400 | Invalid definition or unknown field; `errors` lists the problems |
| 402 | Plan limit (`code`: `plan_required`): no free production workflow slot, or the FINMA profile is not in the plan |
| 403 | The key lacks the scope, names another environment, or a partner app's connection lacks the setup right |
| 404 | No workflow with this id among the key's environment's workflows |
| 409 | The workflow cannot be published as it is (for example a document its environment does not offer) |
| 429 | More 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.
