Skip to main content
Send cal-api-version: 2026-09-22 to author conditional paths and filters through the workflow POST and PATCH endpoints. All API versions return path definitions on GET. The endpoint reference documents the 2026-09-22 contract. Omitted or older version headers continue to use the legacy echo-only contract. The condition-fields discovery endpoints require 2026-09-22.

​
Create a workflow with paths

Generate a UUID for each branch you want to reference in the same request. This example creates two unconditional branches; add conditions using the field catalog described below. Replace the API key and event type ID with your own.
The same step shapes work on organization/team event-type workflows at /v2/organizations/{orgId}/teams/{teamId}/workflows. Routing-form workflows retain their existing echo-only API contract; author their paths in the canvas.

​
Discover and write conditions

Read the catalog for the workflow you want to edit:
  • GET /v2/workflows/{workflowId}/condition-fields
  • GET /v2/organizations/{orgId}/teams/{teamId}/workflows/{workflowId}/condition-fields
Each field provides its id, type, supported operators, allowed options, missingFrom warnings and hasTypeConflict. Operator IDs are the canvas’s raw keys: for example, a text comparison can use equal, while a select uses select_equals. Use IDs and option values from your catalog, not labels. For example, if your catalog includes a text field with ID company, a condition can be:
Condition IDs are generated when omitted. Send the returned IDs when updating conditions. New or changed conditions must be valid for the effective trigger and activation. Unchanged conditions can be echoed even if their field was subsequently removed. The catalog includes at most 100 active entities. truncated: true means the catalog is incomplete; changed conditions cannot be authored against that partial catalog. Reduce the activation scope before authoring them. An empty activation scope returns no fields.

​
Update the complete step list

On version 2026-09-22, PATCH with steps replaces the desired step list:
  • Include every sending step and gate you want to retain, using the IDs returned by GET.
  • Omit a gate or sending step to delete it. Remove references to deleted paths from the remaining steps.
  • Omit a sending step’s pathId to make it unconditional.
  • Omit steps entirely to leave the graph unchanged, for example when renaming a workflow.
  • Omit paths on an existing paths step to preserve its branches and conditions. When supplying paths, include every branch you want to retain.
  • Existing delay and lead enrichment steps must still be echoed by ID and keep their relative order; the API cannot create or edit them.
  • A delay or lead enrichment step keeps its branch membership, so the gate owning that branch cannot be deleted through the API. Remove it on the canvas.
  • A request accepts at most 100 steps.
The API numbers unconditional steps first, followed by gates and their descendants. Gates do not take stepNumber. A split requires at least two branches, and a workflow supports at most one split. Filters can be nested without cycles. Existing path IDs cannot move between gates, and condition IDs cannot move between paths. Each branch or filter accepts four matching modes:
  • all: every condition matches.
  • any: at least one condition matches.
  • none: no conditions match.
  • not_all: at least one condition does not match. For example, with “country is US” and “company size is enterprise,” the branch matches unless both conditions are true.
Omitting matches preserves an existing mode and defaults to all for a new branch. GET returns the exact mode, including not_all for paths previously created in the canvas. Echoing it preserves the rule; sending another mode changes it. The API does not expose database conjunction or negation flags. A filter carries conditions, matches and its owned gatedPathId on the step itself. Member steps reference that gatedPathId through pathId. Generate the UUID yourself when creating a filter and members in one request.

​
Migrate older callers

Without the new version header, PATCH continues to require an echo of every existing paths/filter gate and member step by ID. Their definitions and memberships are preserved; path-authoring fields in an old-version echo are ignored. Old versions cannot create gates. When opting into 2026-09-22, update your client to send the complete desired step list and each retained member’s pathId. Previously omitted steps could be protected by the legacy echo guard; the new contract treats omissions as deletions. Validation or ownership rejection leaves the workflow graph and activation unchanged.