Skip to content

API reference

Submissions

Read the inbox, page back through it, mark spam, run flows again, send test submissions, open uploaded files and delete what you no longer need.

List submissions

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

Newest first. Test submissions are left out unless you ask for them.

Query

formstring
Only submissions of this form id.
sourcestring
Only submissions from this source id.
statusstring
One of received, delivered, failed, invalid or spam.
sinceISO date
Only submissions received at or after this time.
beforeISO date
Only submissions received before this time. Use next_before from the last answer to get the next page.
include_testboolean
true adds test submissions.
limitnumber
1 to 100. 50 when left out.
cURL
curl "https://formpik.com/api/v1/submissions?form=frm_q8w2e4r6t1&limit=20" \
  -H "Authorization: Bearer $FORMPIK_API_KEY"
200 OK
{
  "data": [
    {
      "id": "sub_7k2m9x4q1w3e5r6t",
      "form_id": "frm_q8w2e4r6t1",
      "source_id": "src_m3n5b7v9c1",
      "status": "delivered",
      "test": false,
      "received_at": "2026-11-20T09:30:00.000Z",
      "data": {
        "email": "jane@example.com",
        "topic": "sales",
        "interests": ["speed", "support"]
      }
    }
  ],
  "next_before": "2026-11-20T09:30:00.000Z"
}

next_before is null when there are no more submissions. Answers in data are exactly what was sent: option values rather than labels, and numbers as text.

Read every page

JavaScript
let before = null
const all = []

do {
  const url = new URL("https://formpik.com/api/v1/submissions")
  url.searchParams.set("limit", "100")
  if (before) url.searchParams.set("before", before)

  const response = await fetch(url, { headers: { Authorization: `Bearer ${process.env.FORMPIK_API_KEY}` } })
  const page = await response.json()

  all.push(...page.data)
  before = page.next_before
} while (before)

Read one submission

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

Adds the page it was sent from, the country, why it was caught as spam, the files and every flow run with its steps.

200 OK
{
  "data": {
    "id": "sub_7k2m9x4q1w3e5r6t",
    "form_id": "frm_q8w2e4r6t1",
    "source_id": "src_m3n5b7v9c1",
    "status": "delivered",
    "test": false,
    "received_at": "2026-11-20T09:30:00.000Z",
    "data": { "email": "jane@example.com", "topic": "sales", "brief": "brief.pdf" },
    "meta": {
      "page_url": "https://yourcompany.com/contact",
      "referrer": null,
      "country": "DE",
      "user_agent": "Mozilla/5.0 ...",
      "spam_reasons": []
    },
    "files": [
      { "id": "fil_4r6t8y0u2i4o", "field": "brief", "filename": "brief.pdf", "size": 182044, "content_type": "application/pdf" }
    ],
    "runs": [
      {
        "id": "run_2w4e6r8t0y2u",
        "flow_id": "flw_9o7i5u3y1t",
        "flow_name": "Route new leads",
        "status": "completed",
        "outcome": "delivered",
        "test": false,
        "started_at": "2026-11-20T09:30:01.120Z",
        "duration_ms": 1302,
        "steps": [
          { "node_id": "step_trigger", "kind": "trigger", "label": "Contact submitted", "status": "success", "summary": "Received a submission for \"Contact\"", "details": [], "branch": null, "at": "2026-11-20T09:30:01.124Z" },
          { "node_id": "step_slack", "kind": "slack", "label": "Post to Slack", "status": "success", "summary": "Posted to #sales-leads", "details": [], "branch": null, "at": "2026-11-20T09:30:02.420Z" }
        ]
      }
    ]
  }
}

Open an uploaded file

GEThttps://formpik.com/api/v1/submissions/{id}/files/{fileId}

Answers with a private url that works for 15 minutes and its expires_at. Add ?download=true for a save-as link.

Mark as spam, or release

PATCHhttps://formpik.com/api/v1/submissions/{id}

Send {"spam": true} or {"spam": false}. Needs a key with full or admin access.

Releasing a submission that the endpoint held back as spam runs its flows now, for real. Releasing one that already ran puts it back to the status of its runs.

Run flows again

POSThttps://formpik.com/api/v1/submissions/{id}/rerun

Runs every live flow of the submission again and answers with the updated submission. Needs a key with full or admin access.

Send a test submission

POSThttps://formpik.com/api/v1/submissions/test

Stores a submission marked as a test and runs the form's live flows on it, simulated. Answers 201. Needs a key with full or admin access.

Body

form_idstringrequired
The form it is for.
dataobjectrequired
The answers, keyed by field key. Text, numbers, true and false, or lists of them.
source_idstring
Store it as coming from this source.

Nothing is delivered and it does not count toward your monthly submissions. To send a real submission, post to the source endpoint instead: see Send a submission.

Delete a submission

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

Deletes it with its runs and uploaded files. This cannot be undone. Needs a key with full or admin access.