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 /definitions and run them with POST /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 |
422 with the offending step, task, and field.
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) |
| Field | Type | Description |
|---|
action_version | string | Default "1.0" |
connection_id | string | The connection whose credentials the action uses |
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": "conn_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": "conn_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 /definitions/{id}) before triggering — triggering a draft returns 400.