Concepts

Cascades

What a cascade is, the node grammar behind the definition array, and how to list, create, update, activate and delete cascades through the API.

A cascade is a decision workflow: which reports to pull, in what order, which rules to evaluate, and what happens on each outcome — approve, send to a reviewer, decline with an adverse-action notice. Operators usually author cascades in the visual builder; the API exposes the same objects (the resource is named workflow) so code and agents can list, run, create and edit them.

What does a cascade look like over the API?

JSON

{
  "id": 27,
  "object": "workflow",
  "name": "Tenant Screening Standard",
  "active": true,
  "trigger_type": "manual",
  "use_case": "tenant_screening",
  "created_at": "2026-05-08T18:41:05Z",
  "updated_at": "2026-05-08T18:41:05Z"
}

GET /workflows/{id} adds definition: the node graph as a JSON array. active: false marks a draft — drafts accept a single test-mode trigger but cannot run live, in batches, or be re-evaluated.

What is in the definition?

definition is an array of nodes. Each node has an id, a type, and the edge keys that wire it to the next nodes. The vocabulary is fixed (it is the same grammar the AI generator and the validator use):

Node type	Purpose	Required keys
`ApplicantSource`	Entry point; receives `payload.applicant`	—
`BillingProduct`	Pulls one report (credit, criminal, eviction, identity…)	`billing_product_code`
`IfElse`	Evaluates conditions and branches	`branches`
`Wait`	Pauses for a duration or until a date	`wait`
`GoTo`	Jumps to another node at runtime	`target_step`
`ShowResults`	Terminal node that surfaces the outcome	—
`Action`	Side effect chosen by `action_type`	`action_type`

Product and Condition are accepted as legacy aliases for BillingProduct and IfElse.

Action subtypes (action_type): Approve, SendEmail, AdverseAction, InternalNotification.

Edges. next_step is the default forward edge. An IfElse fans out through pass_steps, human_review_steps and fail_steps — each an array of node ids. That placement is what gives downstream nodes their meaning: an AdverseAction under fail_steps auto-handles a decline; under human_review_steps it prepares a draft at flag time and waits for a reviewer to send it. See Adverse action.

Condition operators inside branches: equals, not_equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal, contains, not_contains, starts_with, ends_with, is_empty, is_not_empty, is_true, is_false. Fields are dotted paths into a product's output, e.g. creditScore.fico9 or searchSummary.recordsFound.

A minimal, runnable definition:

JSON

[
  { "id": "start",  "type": "ApplicantSource", "name": "Applicant", "next_step": ["credit"] },
  { "id": "credit", "type": "BillingProduct", "name": "Credit report",
    "billing_product_code": "TUC1001", "next_step": ["decide"] },
  { "id": "decide", "type": "IfElse", "name": "FICO gate",
    "branches": [{ "conditions": [{ "field": "creditScore.fico9", "operator": "greater_than_or_equal", "value": 680 }] }],
    "pass_steps": ["approve"], "human_review_steps": [], "fail_steps": ["done"] },
  { "id": "approve", "type": "Action", "action_type": "Approve", "name": "Approve", "next_step": ["done"] },
  { "id": "done", "type": "ShowResults", "name": "Results", "next_step": [] }
]

The full schema is CascadeDefinition in the reference.

How do I list and read cascades?

GET /workflows returns the cascades your key's user owns, newest first, paginated. Filter with filter[active]=true, filter[use_case]=tenant_screening or filter[trigger_type]=manual. GET /workflows/{id} returns one with its definition. Both need workflows:read.

Cascades belong to the user behind your key, so two API clients of the same account see the same cascades; executions, by contrast, are isolated per client. See Keys, scopes and rate limits.

How do I create or change one?

POST /workflows with name and definition (and optionally active, trigger_type, use_case) creates a cascade. Needs workflows:write. The definition is validated against the grammar and against the products your account can use; failures come back as 422 validation_failed with one details entry per problem.
PATCH /workflows/{id} changes only the fields you send. To edit the graph, read it, modify the array, and send the whole definition back.
DELETE /workflows/{id} soft-deletes: the cascade disappears from lists and can no longer be triggered; its past executions remain readable.
POST /workflows/generate builds a definition from a plain-English prompt — see Generate a cascade with AI.

Activation is gated

On an unapproved (sandbox) account a new cascade is always saved as a draft, whatever active says, and the response carries a note explaining that; PATCH with active: true is refused with 403 activation_forbidden. Drafts still run in test mode. Once the account is approved, active: true works and live runs become possible. See Sandbox vs live.

Templates

GET /workflow_templates is a read-only catalog of published cascades. Copy a template's definition into POST /workflows to start from something that works.

Executions — running a cascade and reading the outcome
POST /workflows/{id}/trigger
Human review and Adverse action — what the branch placement means at runtime