All docs

API reference: Submissions

Read, edit, delete, bulk-act, export, and download files.

Updated . 6 min read.

Submissions are scoped to a form. All endpoints require a bearer token with the right ability.

Base URL: https://formspring.io/api/v1

Method Path Ability
GET /forms/{form}/submissions submissions:read
POST /forms/{form}/submissions/bulk submissions:write
GET /forms/{form}/submissions/export submissions:export
GET /forms/{form}/submissions/{submission} submissions:read
PUT /forms/{form}/submissions/{submission} submissions:write
DELETE /forms/{form}/submissions/{submission} submissions:write
GET /forms/{form}/submissions/{submission}/files/{file} submissions:read

List submissions

http
GET /forms/{form}/submissions?folder=inbox&per_page=25

Query parameters:

Param Values Default Notes
folder inbox, spam, all inbox
per_page 1-100 25
page integer 1
category string - Filter by AI category
since ISO 8601 - Filter to submissions after this timestamp
until ISO 8601 - Filter to submissions before this timestamp

Response 200: paginated SubmissionCollection. Each entry includes id, status, category, ai_moderation, payload, received_at, plus files if the submission included uploads.

Show a submission

http
GET /forms/{form}/submissions/{submission}

{submission} is the submission ID (subm_...). Returns the full SubmissionResource including raw payload (plus field_ids and data_by_id, the same answers keyed by stable field ID), parsed fields, attached files (with signed download URLs valid for 15 minutes), and metadata.

The submission also carries attribution: the campaign (utm), ad-platform click ids (gclid, fbclid, ttclid, msclkid) and referrer origin the form page captured when the visitor allowed analytics. It is null when they did not, and { "captured_at": ... } alone for a direct visit.

http
GET /forms/{form}/attribution?from=2026-10-01&to=2026-10-31

Where responses came from: each response counted once under its campaign source (else the referrer host, else (direct)), top campaigns, and how many responses carry each click id. Responses without a captured context are (unattributed). Spam, drafts, imports and sample responses are left out. Requires submissions:read; the same report is the get_form_attribution agent tool.

Update a submission

http
PUT /forms/{form}/submissions/{submission}
Content-Type: application/json
json
{
  "payload": { "email": "fixed@example.com" },
  "status": "received"
}

status accepts received, spam, processed, failed. Updating status to spam moves the submission to the spam folder; received moves it back to the inbox.

payload does a shallow merge - fields you don't include are left untouched. To clear a field, set it to null.

Response 200: updated SubmissionResource.

Delete a submission

http
DELETE /forms/{form}/submissions/{submission}

Hard delete. Removes the submission row, attached files, and any audit trail. Cannot be undone.

Response 200: {"ok": true}

Bulk action

http
POST /forms/{form}/submissions/bulk
Content-Type: application/json
json
{
  "ids": ["subm_01H...", "subm_02H..."],
  "action": "delete"
}

action is one of delete, mark_spam, mark_not_spam. Up to 500 IDs per call.

Response 200:

json
{ "ok": true, "affected": 47, "skipped": [] }

skipped lists IDs the caller wasn't allowed to act on (e.g. wrong team).

Export

http
GET /forms/{form}/submissions/export?format=csv

format is csv or json. Returns a streaming response; for large exports the response is chunked, not paginated.

Format Content-Type
csv text/csv; charset=utf-8
json application/json

The CSV includes one column per known field plus metadata columns (id, received_at, status, category, score). Files are referenced by signed URL in a _files column.

Answers are exported under each field's current name, so a renamed field is one column. ?columns=id uses stable field IDs as CSV headers; JSON rows add field_ids and data_by_id. See Stable field IDs.

?since= and ?until= query params apply to exports too. Without them, the export covers all submissions in the form.

Download a file

http
GET /forms/{form}/submissions/{submission}/files/{file}

Returns a 302 Found redirect to a signed URL on object storage. The signed URL is valid for 15 minutes. Follow the redirect to actually download.

{file} is the file ID returned in the files[] array on the submission resource.

This endpoint exists so your code never needs to know the storage backend or hold a long-lived signed URL. Each request mints a fresh one.

Import responses

Bring responses from another platform into a form. The same pipeline as the dashboard import, so a script and the UI behave alike. Needs submissions:write (reading a run needs submissions:read). Imported responses do not use your monthly submission allowance and trigger no notifications, webhooks or automations.

Step Request
Create a run POST /forms/{form}/imports with {"rows": [{...}, ...]} (up to 10,000 rows, 5 MB). Returns the columns found and a suggested mapping. Accepts an Idempotency-Key.
Dry run POST /forms/{form}/imports/{importRun}/dry-run with {"columns": {"Full name": "fld_name"}, "source_id_column": "Submission ID", "timestamp_column": "Submitted at"}. Writes nothing; reports what would be imported, skipped or fail, and what is unresolved (unresolved.unmapped_columns, required_unmapped_fields).
Start POST /forms/{form}/imports/{importRun}/confirm. Needs a dry run of the current mapping. Runs in batches in the background.
Track GET /forms/{form}/imports/{importRun} shows status, processed_rows, imported, skipped, failed and resume_from_row.
Resume POST /forms/{form}/imports/{importRun}/resume continues an interrupted run from where it stopped. Safe to repeat.
Reconcile GET /forms/{form}/imports/{importRun}/reconcile compares counts and a checksum of the ids the run set out to write with what is stored. balanced is true when every row was processed, none failed and the checksums match.
Roll back POST /forms/{form}/imports/{importRun}/rollback removes exactly the responses this run wrote, in the background. Nothing written by other runs or by hand is touched.

Each row is identified by the value in source_id_column, stored as source_id_prefix followed by that value (for example json:src-1). Importing the same rows again skips the ones already stored, so a repeat or a resume never duplicates a response. The checksum is the SHA-256 of those stored ids sorted as strings and joined with a newline.

Common errors

Status Meaning
400 Bad query params (e.g. invalid folder)
401 Token missing or invalid
403 Token lacks required ability
404 Form, submission, or file not found
413 Bulk action exceeded 500 IDs
429 API rate limit hit

What's next