# Flows

Read and build flows as steps and connections, test them on sample answers, and take them live, with the same checks the flow editor runs.

## List flows

`GET https://formpik.com/api/v1/flows`

Newest first. Filter with `?form=frm_...` and `?status=active`, `paused` or `draft`.

## Read one flow

`GET https://formpik.com/api/v1/flows/{id}`

Adds `checks`: whether the flow can go live, what blocks it, and softer warnings.

*200 OK*

```json
{
  "data": {
    "id": "flw_9o7i5u3y1t",
    "name": "Route new leads",
    "description": "",
    "status": "active",
    "form_id": "frm_q8w2e4r6t1",
    "nodes": [
      { "id": "step_trigger", "kind": "trigger", "label": "Contact submitted", "config": { "form_id": "frm_q8w2e4r6t1" }, "position": { "x": 260, "y": 0 } },
      { "id": "step_route", "kind": "route", "label": "Route by answer", "config": { "field": "topic", "cases": [{ "id": "case_sales", "value": "sales" }] }, "position": { "x": 260, "y": 170 } },
      { "id": "step_slack", "kind": "slack", "label": "Post to Slack", "config": { "destination_id": "dst_s4l2c8k1q0", "message": "New lead: {{email}}" }, "position": { "x": 120, "y": 340 } },
      { "id": "step_email", "kind": "email", "label": "Send email", "config": { "to": "support@yourcompany.com", "subject": "New request", "body": "{{submission.all_fields}}" }, "position": { "x": 400, "y": 340 } }
    ],
    "edges": [
      { "id": "edge_1", "source": "step_trigger", "target": "step_route", "source_handle": "out" },
      { "id": "edge_2", "source": "step_route", "target": "step_slack", "source_handle": "case_sales" },
      { "id": "edge_3", "source": "step_route", "target": "step_email", "source_handle": "default" }
    ],
    "checks": { "ready": true, "problems": [], "warnings": [] },
    "created_at": "2026-11-03T10:20:00.000Z",
    "updated_at": "2026-11-19T16:02:11.000Z"
  }
}
```

## Steps and connections

`nodes` are the steps. Each has an `id` you choose (letters, numbers, `-` and `_`, made for you when left out), a `kind`, an optional `label`, its `config`, and an optional `position` on the canvas. Settings you leave out start from the defaults below.

`edges` connect them: `source` and `target` are step ids, and `source_handle` says which way out of a branching step. Steps with one way out can leave it out.

| Kind | What it does | Settings | Ways out |
| --- | --- | --- | --- |
| `trigger` | Starts the flow when a form receives a submission. | `form_id`, and `source_ids` to start only for some sources (empty means all). Defaults: `{}` | `out` |
| `validate` | Check answers and filter out spam before anything is sent. | `use_form_rules`, `block_spam`, and `rules`: a list of `{ id, field, check, value }`. Defaults: `{ "use_form_rules": true, "block_spam": true, "rules": [] }` | `valid` and `invalid` |
| `route` | Send each submission down a different path based on a dropdown or choice. | `field` and `cases`: a list of `{ id, value, operator }`, checked in order. `operator` is `equals` when left out. Defaults: `{ "cases": [] }` | The `id` of each case, and `default` |
| `condition` | Split the flow in two based on one answer. | `conditions`: a list of `{ id, field, operator, value }`, and `match`: `all` or `any`. Operators are listed on [Flows](https://formpik.com/docs/flows#step-condition). Defaults: `{ "operator": "equals", "value": "" }` | `true` and `false` |
| `delay` | Pause before the next step, for follow-ups and reminders. | `amount` and `unit` (`minutes`, `hours` or `days`). Defaults: `{ "amount": 10, "unit": "minutes" }` | `out` |
| `format` | Combine or clean up answers to reuse in later steps. | `assignments`: a list of `{ id, key, template }`. Defaults: `{ "assignments": [] }` | `out` |
| `ai` | Summarize, sort, extract or translate answers, then use the result in later steps. | `ai_task`, `input`, `prompt`, `categories`, `language` and `output_key`. Defaults: `{ "ai_task": "summarize", "input": "{{submission.all_fields}}", "output_key": "ai_summary", "prompt": "", "categories": "", "language": "English" }` | `out` |
| `email` | Email the submission to your team. | `to`, `cc`, `reply_to`, `subject` and `body`. Defaults: `{ "to": "", "subject": "New submission: {{form.name}}", "body": "{{submission.all_fields}}", "reply_to": "{{email}}" }` | `out` |
| `autoreply` | Send a confirmation to the person who filled in the form. | `to`, `subject` and `body`. Defaults: `{ "to": "{{email}}", "subject": "We received your message", "body": "Hi,\n\nThanks for getting in touch. We'll get back to you soon." }` | `out` |
| `slack` | Post a message in a Slack channel. | `destination_id`, `message` and `include_fields`. Defaults: `{ "message": "New submission for {{form.name}}\n{{submission.all_fields}}" }` | `out` |
| `teams` | Post a card in a Microsoft Teams channel. | `destination_id`, `message` and `include_fields`. Defaults: `{ "message": "New submission for {{form.name}}\n{{submission.all_fields}}" }` | `out` |
| `discord` | Send a message to a Discord channel. | `destination_id`, `message` and `include_fields`. Defaults: `{ "message": "New submission for {{form.name}}\n{{submission.all_fields}}" }` | `out` |
| `googlechat` | Post a message in a Google Chat space. | `destination_id`, `message` and `include_fields`. Defaults: `{ "message": "New submission for {{form.name}}\n{{submission.all_fields}}" }` | `out` |
| `mattermost` | Post a message in a Mattermost channel. | `destination_id`, `message` and `include_fields`. Defaults: `{ "message": "New submission for {{form.name}}\n{{submission.all_fields}}" }` | `out` |
| `telegram` | Send a message to a Telegram chat or group through your bot. | `destination_id`, `message` and `include_fields`. Defaults: `{ "message": "New submission for {{form.name}}\n{{submission.all_fields}}" }` | `out` |
| `webhook` | Send the submission as JSON to your CRM, backend or any URL. | `destination_id` and `include_fields`. Defaults: `{ "include_fields": true }` | `out` |

- A flow has exactly one trigger, and nothing can point back into it.
- Connections only move forward: a set of connections that makes a loop is refused.
- Templates in messages use `{{field_key}}`. See [Variables and templates](https://formpik.com/docs/templates). Check values, operators and AI jobs are listed on [Flows](https://formpik.com/docs/flows).

## Create a flow

`POST https://formpik.com/api/v1/flows`

Answers `201` with the new flow. Needs a key with full or admin access.

**Body**

- `name` (string, required): Up to 120 characters.
- `form_id` (string): The form whose submissions start it. Needed when you send no `nodes`; with `nodes`, it sets the trigger's form.
- `template` (string): Without `nodes`: `blank` (the default), `notify`, `confirm` or `route`, the same starting points as the dashboard.
- `nodes, edges` (array): The whole flow, as shown above.
- `status` (string): `draft` (the default), `paused` or `active`.
- `description` (string): Up to 500 characters.

*cURL*

```bash
curl -X POST "https://formpik.com/api/v1/flows" \
  -H "Authorization: Bearer $FORMPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Notify sales", "status": "active", "nodes": [{"id": "start", "kind": "trigger", "config": {"form_id": "frm_q8w2e4r6t1"}}, {"id": "mail", "kind": "email", "config": {"to": "sales@yourcompany.com"}}], "edges": [{"source": "start", "target": "mail"}]}'
```

### Going live

A flow created or changed to `active` has to pass the checks behind Go live in the editor. When it does not, nothing is saved and you get `422` with every problem:

*422 Unprocessable Entity*

```json
{
  "message": "This flow is not ready to go live. Fix the problems listed in problems, or save it as a draft.",
  "code": "flow-not-ready",
  "problems": ["Post to Slack: Pick a destination"]
}
```

## Change a flow

`PATCH https://formpik.com/api/v1/flows/{id}`

Send any of `name`, `description`, `status`, `form_id`, and `nodes` with `edges`. Needs a key with full or admin access.

- `nodes` replaces every step, so send `edges` with it. `edges` alone rewires the current steps.
- Changes to a live flow apply from the next submission.
- Pause a flow with `{"status": "paused"}`.

## Test a flow

`POST https://formpik.com/api/v1/flows/{id}/test`

Runs the flow on answers you send, whatever its status, like the test panel in the editor. Needs a key with full or admin access.

**Body**

- `data` (object): The answers, keyed by field key.
- `source_id` (string): Run as if it came from this source.

Every step is simulated: nothing is delivered or stored, waits are skipped and Ask AI uses a stand-in answer. The answer is the run step by step, with `visited_step_ids` and `visited_connection_ids` for the path it took.

## Duplicate a flow

`POST https://formpik.com/api/v1/flows/{id}/duplicate`

Copies the flow with every step into a new draft flow, like Duplicate in the dashboard. Answers `201`. Counts toward the plan's flows. Needs a key with full or admin access.

**Body**

- `name` (string): The copy's name. The original name with `(copy)` when left out.

## Delete a flow

`DELETE https://formpik.com/api/v1/flows/{id}`

Past runs stay on their submissions. Needs a key with full or admin access.

---

Source: https://formpik.com/docs/api/flows
