> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdialed.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Flow definitions
> The structure of a definition document: inputs, variables, steps, tasks, and exit conditions
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](/concepts/architecture) 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](/concepts/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"` |
| `connection_id` | string | The [connection](/concepts/connections) whose credentials the action uses |
| `parameters` | object | Action input. Values can embed [expressions](/concepts/expressions) like `{{input.message}}` |
| `execution_type` | string | `immediate` (default), `scheduled`, `windowed`, or `signaled` — see [execution models](/concepts/execution-models) |
| `execution_config` | object | Required whenever `execution_type` is not `immediate` |
| `delivery` | string | `direct` (default) or `batched` — see [batching](/concepts/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](/guides/templates) 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](/concepts/expressions) 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.
```json theme={null}
{
"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`.