Skip to content

API reference

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

GEThttps://formpik.com/api/v1/flows

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

Read one flow

GEThttps://formpik.com/api/v1/flows/{id}

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

200 OK
{
  "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.

KindWhat it doesSettingsWays out
triggerStarts the flow when a form receives a submission.form_id, and source_ids to start only for some sources (empty means all). Defaults: {}out
validateCheck 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
routeSend 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
conditionSplit 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. Defaults: { "operator": "equals", "value": "" }true and false
delayPause before the next step, for follow-ups and reminders.amount and unit (minutes, hours or days). Defaults: { "amount": 10, "unit": "minutes" }out
formatCombine or clean up answers to reuse in later steps.assignments: a list of { id, key, template }. Defaults: { "assignments": [] }out
aiSummarize, 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
emailEmail 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
autoreplySend 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
slackPost a message in a Slack channel.destination_id, message and include_fields. Defaults: { "message": "New submission for {{form.name}}\n{{submission.all_fields}}" }out
teamsPost 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
discordSend a message to a Discord channel.destination_id, message and include_fields. Defaults: { "message": "New submission for {{form.name}}\n{{submission.all_fields}}" }out
googlechatPost 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
mattermostPost a message in a Mattermost channel.destination_id, message and include_fields. Defaults: { "message": "New submission for {{form.name}}\n{{submission.all_fields}}" }out
telegramSend 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
webhookSend 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. Check values, operators and AI jobs are listed on Flows.

Create a flow

POSThttps://formpik.com/api/v1/flows

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

Body

namestringrequired
Up to 120 characters.
form_idstring
The form whose submissions start it. Needed when you send no nodes; with nodes, it sets the trigger's form.
templatestring
Without nodes: blank (the default), notify, confirm or route, the same starting points as the dashboard.
nodes, edgesarray
The whole flow, as shown above.
statusstring
draft (the default), paused or active.
descriptionstring
Up to 500 characters.
cURL
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
{
  "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

PATCHhttps://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

POSThttps://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

dataobject
The answers, keyed by field key.
source_idstring
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

POSThttps://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

namestring
The copy's name. The original name with (copy) when left out.

Delete a flow

DELETEhttps://formpik.com/api/v1/flows/{id}

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