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
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
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.
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
PUT /forms/{form}/submissions/{submission}
Content-Type: application/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
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
POST /forms/{form}/submissions/bulk
Content-Type: application/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:
{ "ok": true, "affected": 47, "skipped": [] }
skipped lists IDs the caller wasn't allowed to act on (e.g. wrong team).
Export
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
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 |
