Skip to main content
POST
Start a workflow

Authorizations

Authorization
string
header
required

OAuth 2.0 authorization code flow with PKCE (S256). See the authorization guide.

Scopes

workflows:write

Start workflows, update their names, tags and roles, and move them between stages

Body

application/json
template_id
string<uuid>
required
name
string
required
Required string length: 1 - 200
tag_ids
string<uuid>[]

Active same-firm tag ids. Requires the resource write scope, not tags:write. Omit to preserve, [] to clear; null is rejected. Replaces the entire tag set.

Maximum array length: 100
contact_ids
string<uuid>[]
household_ids
string<uuid>[]
role_users
object

Maps role ids to active firm user ids. Omitted roles keep their current or template default user. Get user ids from GET /users (users:read).

Response

The committed workflow id.

The committed workflow id. Fetch GET /workflows/{id} with workflows:read for its current state. A follow-up read failure never turns a committed write into a failed response.

id
string<uuid>
required