# 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

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

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

**Query**

- `form` (string): Only submissions of this form id.
- `source` (string): Only submissions from this source id.
- `status` (string): One of `received`, `delivered`, `failed`, `invalid` or `spam`.
- `since` (ISO date): Only submissions received at or after this time.
- `before` (ISO date): Only submissions received before this time. Use `next_before` from the last answer to get the next page.
- `include_test` (boolean): `true` adds test submissions.
- `limit` (number): 1 to 100. 50 when left out.

*cURL*

```bash
curl "https://formpik.com/api/v1/submissions?form=frm_q8w2e4r6t1&limit=20" \
  -H "Authorization: Bearer $FORMPIK_API_KEY"
```

*200 OK*

```json
{
  "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*

```js
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

`GET 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.

*200 OK*

```json
{
  "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

`GET 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.

> **Use the link right away**
>
> Fetch the file with the link and store the file itself if you need to keep it. Never save the link or put it in a page: it expires, and anyone holding it can open the file until then.

## Mark as spam, or release

`PATCH 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

`POST https://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.

> **This delivers again**
>
> A real submission sends its emails, chat messages and webhooks again. A submission marked as spam answers `409` until you release it.

## Send a test submission

`POST https://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_id` (string, required): The form it is for.
- `data` (object, required): The answers, keyed by field key. Text, numbers, true and false, or lists of them.
- `source_id` (string): 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](https://formpik.com/docs/api/submit).

## Delete a submission

`DELETE 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.

---

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