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
https://formpik.com/api/v1/submissionsNewest 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,invalidorspam. sinceISO date- Only submissions received at or after this time.
beforeISO date- Only submissions received before this time. Use
next_beforefrom the last answer to get the next page. include_testbooleantrueadds test submissions.limitnumber- 1 to 100. 50 when left out.
curl "https://formpik.com/api/v1/submissions?form=frm_q8w2e4r6t1&limit=20" \
-H "Authorization: Bearer $FORMPIK_API_KEY"{
"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
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
https://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.
{
"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
https://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
https://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
https://formpik.com/api/v1/submissions/{id}/rerunRuns 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
https://formpik.com/api/v1/submissions/testStores 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
https://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.