# flow2act · Prozess starten

Starte die Ausführung einer veröffentlichten Version. Die Daten müssen deren Felddefinition entsprechen.

Optionales documentIds enthält bestätigte Reservierungen derselben startenden Identität und veröffentlichten Flow-Version. Pflichtfelder, Dateianzahl, Ablauf und Mandant werden atomar geprüft. Jedes Dokument kann nur einem Vorgang zugeordnet werden. Prozessdaten enthalten keine Dokument-URL.

flowVersionId: veröffentlichte Versions-UUID, keine Flow-ID. referenceId: Referenz im eigenen System, 1–128 Zeichen, eindeutig pro veröffentlichter Version im Workspace. data: skalare Werte unter dem Feldschlüssel; unbekannte Felder werden abgewiesen. Idempotenz verhindert doppelte Starts.

Ein erfolgreich gestarteter Prozess verbraucht einen Request, unabhängig von API-Aufrufen oder Gate-Anzahl. Free enthält 25 pro monatlichem Nutzungszeitraum. Bestehende Prozesse können nach Erreichen des Startlimits abgeschlossen werden.

Freigabeknoten unterstützen assignment=requester_manager mit groupId=null. Integrationen mit runs:start können requesterPersonId (Personen-ID im Organigramm) angeben. Die direkte Führungskraft benötigt einen aktiven Benutzerzugang. Fehlt sie, folgt 409 MANAGER_UNAVAILABLE. Der Empfänger wird beim Aktivieren des Schritts festgehalten.

Liefert auch bei Wiederholungen einen Beleg mit data={} und leerer referenceId. Nur zugeordnete Freigebende/Reviewer können anschließend die Antragsinhalte abrufen.

## POST /v1/flow-runs

Authentication: restricted integration key (scope: runs:start) or flow2act sign-in access token
Required tenant header: X-Organization-Id.
Required user permissions: Rolle requester erforderlich. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Input parameters
- flowVersionId (string, required): uuid
- referenceId (string, required): min length 1 · max length 128
- requesterPersonId (string, optional): uuid
- data (object, required): 
- documentIds (array, optional): max items 100

## Request example (replace example IDs)

```sh
curl -X POST "https://api.flow2act.com/v1/flow-runs" \
  -H "authorization: Bearer $FLOW2ACT_API_KEY" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001" \
  -H "idempotency-key: example-start-run-001" \
  -H "content-type: application/json" \
  --data-raw '{
  "flowVersionId": "10000000-0000-4000-8000-000000000003",
  "referenceId": "deployment-example-001",
  "data": {
    "environment": "production"
  }
}'
```

## Response excerpt

```json
{
  "id": "10000000-0000-4000-8000-000000000004",
  "status": "waiting",
  "gates": [
    {
      "id": "10000000-0000-4000-8000-000000000005",
      "status": "pending"
    }
  ]
}
```

Source: /docs/start-run
Full schemas: /docs/openapi.json