All docs

API reference: Automations

Every Automations endpoint - CRUD, enable/disable, manual runs, and run history.

Updated . 11 min read.

Per-resource workflows - a trigger, optional conditions, and an ordered list of action steps. Automations hang off a parent resource, so the same endpoints exist under forms, surveys, and funnels. Available on every plan, same token model as the rest of the API.

Base URL: https://formspring.io/api/v1

The paths below use /forms/{form}/...; substitute /surveys/{survey}/... or /funnels/{funnel}/... for the other products.

Method Path Ability
GET /forms/{form}/automations automations:read
POST /forms/{form}/automations automations:write
GET /forms/{form}/automations/{automation} automations:read
PUT /forms/{form}/automations/{automation} automations:write
DELETE /forms/{form}/automations/{automation} automations:write
POST /forms/{form}/automations/{automation}/enable automations:write
POST /forms/{form}/automations/{automation}/disable automations:write
POST /forms/{form}/automations/{automation}/run automations:run
GET /forms/{form}/automations/{automation}/runs automations:read
GET /forms/{form}/automations/{automation}/runs/{run} automations:read
POST /forms/{form}/automations/{automation}/runs/{run}/replay automations:run
POST /forms/{form}/automations/{automation}/runs/{run}/cancel automations:run
POST /forms/{form}/automations/{automation}/runs/{run}/resume automations:run
GET /forms/{form}/automations/{automation}/test-inputs automations:read
POST /forms/{form}/automations/{automation}/test automations:run
GET /forms/{form}/automations/{automation}/versions automations:read
GET /forms/{form}/automations/{automation}/versions/{version} automations:read
POST /forms/{form}/automations/{automation}/versions/{version}/restore automations:write
GET /automation-limits automations:read
PUT /automation-limits automations:write
GET /workspace/automation-templates automations:read
GET /workspace/automation-templates/{template} automations:read
POST /workspace/automation-templates/{template}/install automations:write

Workspace automations. Automations that start on workspace events (a contact is created or changed, a trial ends, a plan changes, a member is invited or removed, desk and other lifecycle triggers) belong to the workspace of the token, not to a product. They use /workspace/automations in place of /forms/{form}/automations, with the same endpoints, abilities and bodies and no id in the path. The trigger must be one a workspace can use, and plan-gated triggers and actions are checked on save, exactly as in the builder.

The {form}/{survey}/{funnel} parameter takes the parent's public id (funnels also accept the slug). {automation} and {run} are numeric ids. An automation is only reachable under the parent it belongs to - mismatches 404.

List automations

http
GET /forms/{form}/automations

Returns every automation on the parent, each with its ordered steps array, newest first.

Create an automation

http
POST /forms/{form}/automations
Content-Type: application/json

{
  "name": "Route demo requests to sales",
  "trigger_type": "submission.created",
  "trigger_config": {},
  "is_active": true,
  "steps": [
    { "position": 1, "kind": "condition", "config": { "field": "topic", "operator": "equals", "value": "demo" } },
    { "position": 2, "kind": "action", "action_key": "send_email", "config": { "to": "sales@example.com" } }
  ]
}
  • name required (max 120 chars)
  • trigger_type required - e.g. submission.created, submission.updated, submission.tagged, submission.marked_spam, submission.starred, manual, schedule.cron, webhook.failed. Survey parents add survey_submission.created and survey.outcome_matched; funnel parents add funnel_submission.created. See Triggers →.
  • trigger_config - trigger-specific options (e.g. the cron expression)
  • is_active - defaults to true
  • steps - ordered list of steps (condition, action, delay, branch, fork, join, foreach, child_workflow); action_key picks the action (see Actions →). The steps are checked as a whole, exactly as in the dashboard builder, and a 422 names the field that is wrong (steps.0.config.body_count, steps.1.config.automation_id); nothing is saved when they are refused.
  • A foreach step takes items (the path of the list), body_count (how many of the steps right after it it repeats; only action steps, inside the same branch) and optionally max_items. A child_workflow step takes automation_id (another workflow of the workspace; a cycle or more than three levels is refused), wait and optionally input.

Response 201: the automation with its steps.

Show / update an automation

http
GET /forms/{form}/automations/{automation}
PUT /forms/{form}/automations/{automation}

PUT accepts name, description, trigger_type, trigger_config, is_active, and run_order. Steps are managed through the dashboard builder. Returns the fresh automation with steps.

Enable / disable

http
POST /forms/{form}/automations/{automation}/enable
POST /forms/{form}/automations/{automation}/disable

Flips is_active. Disabled automations keep their run history but stop firing on triggers.

Delete an automation

http
DELETE /forms/{form}/automations/{automation}

Response 200: { "ok": true }. Deletion is processed asynchronously, consistent with every destructive action on the platform.

Run manually

http
POST /forms/{form}/automations/{automation}/run

Queues a manual run regardless of the configured trigger. Requires the dedicated automations:run ability (separate from automations:write so editing tokens can't fire side effects).

Response 202: { "run_id": 481 } - the run executes asynchronously; poll the run endpoint for status.

List runs

http
GET /forms/{form}/automations/{automation}/runs?status=failed&per_page=25

Cursor-paginated run history, newest first. Filters: status (pending, running, succeeded, failed, skipped), from / to date bounds, per_page (1-100, default 25).

Response 200:

json
{
  "data": [
    { "id": 481, "status": "failed", "started_at": "2026-06-09T08:00:01+00:00", "finished_at": "2026-06-09T08:00:04+00:00" }
  ],
  "next_cursor": "eyJpZCI6NDgxfQ",
  "prev_cursor": null
}

Pass next_cursor back as ?cursor= to fetch the next page.

Show a run

http
GET /forms/{form}/automations/{automation}/runs/{run}

Returns the run's scalar fields plus an ordered, typed list of step runs:

json
{
  "id": 481,
  "automation_id": 12,
  "submission_id": 90341,
  "status": "failed",
  "started_at": "2026-06-09T08:00:01+00:00",
  "finished_at": "2026-06-09T08:00:04+00:00",
  "error": "send_email: SMTP 550 mailbox unavailable",
  "created_at": "2026-06-09T08:00:00+00:00",
  "steps": [
    { "position": 1, "kind": "condition", "status": "succeeded", "started_at": "2026-06-09T08:00:01+00:00", "finished_at": "2026-06-09T08:00:01+00:00", "duration_ms": 12, "error": null },
    { "position": 2, "kind": "action", "status": "failed", "started_at": "2026-06-09T08:00:01+00:00", "finished_at": "2026-06-09T08:00:04+00:00", "duration_ms": 2710, "error": "send_email: SMTP 550 mailbox unavailable" }
  ],
  "failed_step_position": 2
}

The branches array lists the branches a fork in this run started, each with lane, status, error and finished_at; a branch run carries branch (its lane) and parent_run_id. children lists the child workflows this run started (id, automation_id, automation_name, status, error), and child_of names the run that started this one when it is itself a child. Steps repeated by a loop carry an iteration (0-based) and every step carries its action_key.

Cancel a run

http
POST /forms/{form}/automations/{automation}/runs/{run}/cancel

Stops a run that has not finished: it executes no further step, a delayed or waiting run is not woken again, and its child and branch runs are cancelled with it. Requires automations:run.

Response 200: { "cancelled": true, "status": "cancelled" }. Response 409 with "cancelled": false when the run had already finished.

Resume a run

http
POST /forms/{form}/automations/{automation}/runs/{run}/resume

Puts a failed run, a run that needs review or a run paused by a limit back on the queue at the step that stopped it; steps that already went out are not repeated. Requires automations:run and the right to change the automation. A run that needs review needs a decision in the body: { "resolution": "mark_sent" } when the provider confirmed the request arrived, or { "resolution": "retry" } to send it again, which may deliver it twice.

Response 202: { "run_id": "123", "status": "pending" }. Response 422 when the run is not in a state that can be resumed (including a run that is already pending, so a second call never queues it twice) or when resolution is missing or unknown. Send an Idempotency-Key header and a repeat of the call answers what the first one did.

Test with a past run

http
GET  /forms/{form}/automations/{automation}/test-inputs
POST /forms/{form}/automations/{automation}/test

test-inputs lists the data the newest runs started with (run_id, status, created_at, sample), with secrets removed and personal data (emails, phone numbers, names, addresses, IP addresses) masked. test walks the saved automation against a sample object or against from_run_id and reports what each step would do, following an error route when a step would fail; nothing is sent, requested or saved and no run is recorded. A sample in the body wins over from_run_id. Response 422 when from_run_id is not a run of this automation or its data is too large to test with.

Versions

Every save is kept as an immutable version; a run finishes on the version it started with.

http
GET  /forms/{form}/automations/{automation}/versions
GET  /forms/{form}/automations/{automation}/versions/{version}
POST /forms/{form}/automations/{automation}/versions/{version}/restore

The list is newest first (?limit= 1-100, default 50) with the version number, why it was saved, who saved it, whether it is the current one and its step count. Reading one version returns the trigger, retry settings and every step with sensitive settings masked, plus connections: the workspace connections the version relies on, by id, with their current state (status, deliverable, message; missing when the connection was removed). A version never contains a credential. Restoring never rewrites history: the restored definition becomes the newest version (201), and repeating the call changes nothing. Check connections first when the version names a connection that now needs reconnecting.

Workspace template library

http
GET  /workspace/automation-templates
GET  /workspace/automation-templates/{template}
POST /workspace/automation-templates/{template}/install

The list returns every library template with its key, name, description, category, trigger_type, steps_count, the parameters it takes, what it requires from the plan, and whether this workspace can install it now (available, with unavailable_reason when not). The preview adds trigger_config and the ordered steps, each with a plain-words summary; pass ?parameters[notify_email]=ops@example.com to see it with your own settings (they default to the address of the token's user). Install saves the template as a workspace automation and answers 201 with it. It is switched off unless the body says "activate": true, and name and parameters are optional. Installing runs the same validation and plan checks as creating a workspace automation: a template the plan cannot run answers 422 and creates nothing. Send an Idempotency-Key to make a retry safe. An unknown key answers 404.

Limits and AI usage

http
GET /automation-limits
PUT /automation-limits

Returns the plan limits, the workspace's own lower caps and today's usage. usage.ai_credits carries balance (credit-pack credits left), unlimited (AI is included in the plan), actions_today and daily_budget for the automations' AI steps, and when the budget resets. A cap can be lowered, never raised above the plan.

Replay a run

http
POST /forms/{form}/automations/{automation}/runs/{run}/replay

Dispatches a fresh run against the same submission (when the original run had one). Requires automations:run.

Response 202: { "run_id": 502 } - the new run records which run it replays.

Errors

Status When
402 Team's plan doesn't include API access
403 Token missing required ability
404 Parent or automation doesn't belong to the current team, or the automation isn't owned by that parent
422 Validation failed (missing name or trigger_type, bad status filter, ...)

See also

  • Automations overview → - triggers, conditions, actions, and examples
  • Tokens & abilities →
  • MCP server → - the same surface as agent tools (list_automations, create_automation, run_automation, replay_automation_run, cancel_automation_run, list_automation_versions, get_automation_version, restore_automation_version, ...)