Start a process

How it works

Optional documentIds contains ready reservations from the same starting identity and published flow version. Required fields, per-field counts, expiry and tenant are checked atomically. Each document can be bound to one run only. No document URL is included in run data.

flowVersionId: published version UUID, not a flow ID. referenceId: your system reference, 1–128 characters, unique per published version in the workspace. data: scalar values keyed by field key; unknown fields are rejected. Use idempotency to prevent duplicate starts.

One successfully started process consumes one request, regardless of API calls or gate count. Free includes 25 per monthly usage period. Existing processes can still complete after the start limit is reached.

Approval nodes can use assignment=requester_manager with groupId=null. An integration with runs:start may pass requesterPersonId (directory person ID). The direct manager must have active user access; missing assignments return 409 MANAGER_UNAVAILABLE. The recipient is frozen when the step activates.

Returns a receipt with data={} and an empty referenceId, including retries. Only assigned approvers/reviewers can subsequently retrieve submitted content.

Request body

Request essentials

Authorization

Bearer $FLOW2ACT_API_KEY

X-Organization-Id

Your workspace UUID

Idempotency-Key

Stable per operation; 8–128 characters