Flow definitions

A definition is the blueprint for a flow. It declares what data the flow accepts, the steps it performs, and how it reacts to success and failure. You create definitions with POST /flows/definitions and run them with POST /flows/definitions/{id}/trigger — see how GetDialed works for the big picture.

Top-level structure

Field	Type	Description
`name`	string	Human-readable definition name
`version`	integer	Version number. Default `1`
`status`	string	`draft` (default), `active`, or `archived`. Only `active` definitions can be triggered
`inputs`	array	Input declarations — the data callers pass at trigger time
`variables`	array	Named constants available to every step
`steps`	array	The workflow steps, run in order. Max 150 steps, max 50 tasks per step
`webhooks`	array	Webhook configurations

Expression syntax is validated when you create or update a definition — a malformed expression returns 422 with the offending step, task, and field.

Inputs

Inputs declare the data a caller provides in input_data when triggering. Each input has:

Field	Type	Description
`name`	string	The key referenced as `{{input.name}}` in task parameters
`type`	string	`string`, `number`, `boolean`, `object`, `array`, or `datetime`
`required`	boolean	Default `true`
`description`	string	Optional documentation for the input

Variables

Variables are definition-level values — thresholds, list names, feature switches — referenced as {{var.name}}. Each has a name, a type (same set as inputs), and a value. Changing a variable means updating the definition, so use them for values that change per version, and use inputs for values that change per trigger.

Steps and tasks

Steps run sequentially; the tasks inside a step run concurrently. Each step has a step_id (unique within the definition), an optional name, a list of tasks, and optional exit_conditions. Every task requires five identifying fields:

Field	Type	Description
`task_id`	string	Unique across all steps in the definition. Later steps reference this task’s output as `{{step_id.task_id.output.field}}`
`task_name`	string	Human-readable label
`platform_id`	string	The platform from the catalog (e.g., `five9`)
`service_id`	string	The service within that platform
`action_id`	string	The action to run (e.g., `five9__configuration_service__add_to_list`)

And supports these optional fields:

Field	Type	Description
`action_version`	string	Default `"1.0"`. Reserved — action versions are not resolved today, so the task always runs the action’s single current implementation. It is still validated: a value disagreeing with the version the action is published at in the catalog is rejected. Omit it unless you have a reason not to
`connection_id`	string	The credential the action runs with — a `cred_` id. Required whenever the action’s service reports `requires_connection: true`. The field name is retained for workflow-history compatibility; the value is a credential id
`parameters`	object	Action input. Values can embed expressions like `{{input.message}}`
`execution_type`	string	`immediate` (default), `scheduled`, `windowed`, or `signaled` — see execution models
`execution_config`	object	Required whenever `execution_type` is not `immediate`
`delivery`	string	`direct` (default) or `batched` — see batching
`batch_config`	object	Required when `delivery` is `batched`
`on_success`	string	`continue` (default), `skip_step`, or `abort_execution`
`on_failure`	string	`abort_step` (default), `abort_execution`, `log_and_continue`, or `retry`
`template_id`	string	The template this task was created from, if any
`notes`	string	Free-form notes

task_id values must be unique across the entire definition — not just within their step — and step_id values must be unique too. Duplicates are rejected at creation time.

Success and failure policies

on_failure: abort_step (default) — the task’s error fails the execution.
on_failure: log_and_continue — the task records a failed result and the flow proceeds.
on_success: skip_step — a successful result skips the remaining tasks in the current step.
on_success: abort_execution / on_failure: abort_execution — stop the whole execution.

Exit conditions

Exit conditions run after all tasks in a step finish. Each pairs a boolean expression with an action:

Field	Description
`condition`	An expression comparison, e.g. `{{check.fetch.output.status}} == "failed"`
`action`	`continue`, `abort_execution`, `skip_next_step`, or `trigger_definition`
`reason`	Optional explanation recorded with the outcome
`definition_id`, `inputs`	For `trigger_definition`: the definition to start and the inputs to pass it

Complete example

A two-step definition: fetch Five9 contact lists, then add a record to one of them during business hours.

{
  "name": "Add prospect during business hours",
  "status": "active",
  "inputs": [
    {"name": "phone", "type": "string", "required": true, "description": "Prospect phone number"},
    {"name": "first_name", "type": "string", "required": false}
  ],
  "variables": [
    {"name": "list_name", "type": "string", "value": "prospects"}
  ],
  "steps": [
    {
      "step_id": "lookup",
      "name": "Fetch contact lists",
      "tasks": [
        {
          "task_id": "get_lists",
          "task_name": "Get Five9 lists",
          "platform_id": "five9",
          "service_id": "configuration_service",
          "action_id": "five9__configuration_service__get_lists",
          "connection_id": "cred_abc12345",
          "parameters": {"list_name": "{{var.list_name}}"}
        }
      ],
      "exit_conditions": [
        {
          "condition": "{{lookup.get_lists.output.count}} == 0",
          "action": "abort_execution",
          "reason": "Target list does not exist"
        }
      ]
    },
    {
      "step_id": "add",
      "name": "Add prospect to list",
      "tasks": [
        {
          "task_id": "add_record",
          "task_name": "Add record to list",
          "platform_id": "five9",
          "service_id": "configuration_service",
          "action_id": "five9__configuration_service__add_to_list",
          "connection_id": "cred_abc12345",
          "execution_type": "windowed",
          "execution_config": {
            "timezone": "America/New_York",
            "window": {
              "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
              "start_time": "09:00",
              "end_time": "17:00"
            },
            "outside_window": "schedule_next"
          },
          "parameters": {
            "list_name": "{{var.list_name}}",
            "records": [{"first_name": "{{input.first_name | default:\"Unknown\"}}", "phone": "{{input.phone}}"}]
          },
          "on_failure": "log_and_continue"
        }
      ]
    }
  ]
}

Definitions start as draft. Set status to active (at creation or via PUT /flows/definitions/{id}) before triggering — triggering a draft returns 400.

Deleting a definition

DELETE /flows/definitions/{id} removes a definition. If any schedules still reference it, the delete is refused with 409 so a live schedule is never left firing into a definition that no longer exists. The response body lists the blocking schedules:

{
  "message": "Definition has bound schedules; delete them first",
  "schedule_ids": ["sched_1a2b", "sched_3c4d"]
}

Delete each listed schedule with DELETE /flows/schedules/{id}, then retry the definition delete. Batches and executions the definition already produced are unaffected.

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

Top-level structure

Inputs

Variables

Steps and tasks

Success and failure policies

Exit conditions

Complete example

Deleting a definition

​Top-level structure

​Inputs

​Variables

​Steps and tasks

​Success and failure policies

​Exit conditions

​Complete example

​Deleting a definition

Top-level structure

Inputs

Variables

Steps and tasks

Success and failure policies

Exit conditions

Complete example

Deleting a definition