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

Searchable inputs

Support work starts from a business key — a lead id, a phone number, a list name — not from an execution id. searchable_inputs names up to five of a definition’s inputs whose values should be recorded on every run, so runs can be looked up by them afterwards.

{
  "name": "New lead follow-up",
  "inputs": [
    { "name": "lead_id", "type": "string" },
    { "name": "customer", "type": "object" }
  ],
  "searchable_inputs": ["lead_id", "customer.phone"]
}

An entry is either an input name or a dotted path into one, which is how a per-record flow makes a field of each record searchable. The query key is the path lowercased, with dots replaced by underscores. customer.phone is filtered as attr.customer_phone; lead_id is filtered as attr.lead_id. See finding a run by business key for the filter itself. A few rules are worth knowing before you declare one:

Values are captured when the run starts and never change. Editing searchable_inputs afterwards changes what future runs record; it does not rewrite what past runs were found by. A run’s search keys describe what it started with.
Phone-shaped values are stored in international format. A run started with (707) 634-2533 is found by attr.phone=%2B17076342533, and so is one started with +1 707 634 2533. A value that cannot be read as a phone number is stored exactly as it arrived, so it is still findable.
Values longer than 256 characters are shortened, and values that are not simple — an object or a list — are not recorded at all, because there is nothing to match them against exactly.
Naming an input the definition does not declare is rejected with 422 when you save the definition, as is declaring more than five, or two entries that produce the same key.

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`
`retry_policy`	object	How the task re-attempts itself when `on_failure` is `retry` — see retrying a task
`template_id`	string	The template this task was created from, if any
`skip_if`	string	A condition that decides whether this task runs at all — see skipping a task. Omit it and the task always runs
`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_failure: retry — the task is attempted again before the flow gives up. See retrying a task.
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.

Retrying a task

retry_policy says how a task re-attempts itself after a failure. It applies only when the task’s on_failure is retry; declaring a policy without it is rejected when the flow is saved.

Field	Type	Description
`max_attempts`	integer	How many times the task may run in total, counting the first attempt. Between 1 and 10. Default `3`
`initial_delay`	string	How long to wait before the second attempt, written as a duration such as `5s`, `30s` or `2m`. Between one second and one hour. Default `"5s"`
`backoff`	string	`exponential` (default) doubles the wait each time; `fixed` keeps it the same
`retry_on`	string	`transient` (default) or `any` — see below

What transient means. Every action reports whether a failure was temporary — a timeout or a refused connection reaching the provider — or final. retry_on: transient retries only the temporary ones. retry_on: any also retries failures the action did not classify. Neither ever retries a failure the action reported as final: if the action says the work will not succeed on a second try, it is believed. Not every action can be retried. Every action in the catalog declares how safe it is to repeat, and that declaration bounds what you can ask for:

An action that must never be repeated refuses a retry policy outright. Saving the flow returns a 422 naming the action.
An action that must not be repeated blindly accepts a policy only with retry_on: transient.
An action that is safe to repeat freely accepts any policy.

The reason is that repeating a call which may already have reached the provider can duplicate real work — sending a message twice, or dialing a consumer twice. The bound is also checked while the flow runs, so an action that is reclassified after your flow was saved stops being retried straight away. Retry a lookup that occasionally times out:

{
  "task_id": "lookup",
  "task_name": "Fetch the account record",
  "platform_id": "getdialed",
  "service_id": "getdialed__http",
  "action_id": "getdialed__http__request",
  "on_failure": "retry",
  "retry_policy": {
    "max_attempts": 4,
    "initial_delay": "10s",
    "backoff": "exponential",
    "retry_on": "transient"
  },
  "parameters": {
    "url": "https://api.example.com/accounts/{{input.account_id}}"
  }
}

That task runs at most four times, waiting 10 seconds, then 20, then 40 — and only when the action reported the failure as temporary.

A retry policy and provider rate limits do not stack. See retry policies and pacing.

Skipping a task

skip_if puts a condition on a single task. It is evaluated immediately before the task would run, against the same context the task’s parameters see, and it uses the same syntax as a step’s exit condition — a comparison such as {{input.email}} == null, or a bare expression, which passes when it resolves to a truthy value. See conditions for the full syntax. When the condition passes, the task does not run, it is recorded as skipped, and the rest of the step still runs. That is the difference from on_success: skip_step: skip_step skips the tasks that follow a task that did run, while skip_if skips only the one task it is written on. A skipped task’s on_success and on_failure never apply — it neither succeeded nor failed. Later steps can see what happened: the skipped task’s output carries _skipped: true, so {{send.receipt.output._skipped}} resolves to true when the task was skipped. Send the receipt only when an address is present:

{
  "step_id": "send",
  "name": "Notify the customer",
  "tasks": [
    {
      "task_id": "receipt",
      "task_name": "Email the receipt",
      "platform_id": "postmark",
      "service_id": "postmark__email",
      "action_id": "postmark__email__send",
      "connection_id": "cred_abc12345",
      "skip_if": "{{input.email}} == null",
      "parameters": {
        "to": "{{input.email}}",
        "subject": "Your receipt",
        "text_body": "Thanks for your order."
      }
    },
    {
      "task_id": "log",
      "task_name": "Record the outcome",
      "platform_id": "getdialed",
      "service_id": "getdialed__utils",
      "action_id": "getdialed__utils__echo",
      "parameters": {"emailed": "{{input.email}}"}
    }
  ]
}

If input.email is absent, receipt is skipped and log still runs.

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

Searchable inputs

Variables

Steps and tasks

Success and failure policies

Retrying a task

Skipping a task

Exit conditions

Complete example

Deleting a definition

​Top-level structure

​Inputs

​Searchable inputs

​Variables

​Steps and tasks

​Success and failure policies

​Retrying a task

​Skipping a task

​Exit conditions

​Complete example

​Deleting a definition

Top-level structure

Inputs

Searchable inputs

Variables

Steps and tasks

Success and failure policies

Retrying a task

Skipping a task

Exit conditions

Complete example

Deleting a definition