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
GET /forms/{form}/automations
Returns every automation on the parent, each with its ordered steps array, newest first.
Create an automation
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" } }
]
}
namerequired (max 120 chars)trigger_typerequired - e.g.submission.created,submission.updated,submission.tagged,submission.marked_spam,submission.starred,manual,schedule.cron,webhook.failed. Survey parents addsurvey_submission.createdandsurvey.outcome_matched; funnel parents addfunnel_submission.created. See Triggers →.trigger_config- trigger-specific options (e.g. the cron expression)is_active- defaults totruesteps- ordered list of steps (condition,action,delay,branch,fork,join,foreach,child_workflow);action_keypicks the action (see Actions →). The steps are checked as a whole, exactly as in the dashboard builder, and a422names the field that is wrong (steps.0.config.body_count,steps.1.config.automation_id); nothing is saved when they are refused.- A
foreachstep takesitems(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 optionallymax_items. Achild_workflowstep takesautomation_id(another workflow of the workspace; a cycle or more than three levels is refused),waitand optionallyinput.
Response 201: the automation with its steps.
Show / update an automation
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
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
DELETE /forms/{form}/automations/{automation}
Response 200: { "ok": true }. Deletion is processed asynchronously, consistent with every destructive action on the platform.
Run manually
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
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:
{
"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
GET /forms/{form}/automations/{automation}/runs/{run}
Returns the run's scalar fields plus an ordered, typed list of step runs:
{
"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
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
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
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.
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
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
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
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, ...)
