Submissions
A submission is either normal or spam. There’s no status to manage.
- GET
/v1/forms/{formId}/submissionssubmissions:read - A form's submissions, newest first.
- GET
/v1/sites/{siteId}/submissionssubmissions:read - Every form's on the site, newest first. Also takes
form. - GET
/v1/sites/{siteId}/submissions/countssubmissions:read - How many there are in each view:
{ all, spam, blocked, unfinished, unfinishedWithDetails }. - GET
/v1/forms/{formId}/submissions/exportsubmissions:read - Every match as a stream: CSV (
Accept: text/csv, the default) or NDJSON (Accept: application/x-ndjson). - GET
/v1/submissions/{id}submissions:read - One submission.
- POST
/v1/submissions/{id}/spamsubmissions:write - Marks it spam, stops what was still to be sent and stops counting it.
- POST
/v1/submissions/{id}/not-spamsubmissions:write - Undoes that, and sends anything that never went.
- DELETE
/v1/submissions/{id}submissions:write - Deletes it and its files for good.
- POST
/v1/forms/{formId}/submissions/bulksubmissions:write { action: "spam" | "not-spam" | "delete", ids }, up to 100. Answers per item, so one failure doesn't stop the rest.
Filters
Section titled “Filters”List, counts and export take the same filters:
| Filter | Values |
|---|---|
state |
complete (the default), pending_payment, abandoned |
quota |
counted, held |
spam |
true, false (the default) |
test |
true, false (the default) |
tag |
a tag; repeat it for several |
from, to |
RFC 3339 times |
q |
searches answers and their display text: each word (up to 5, 200 characters in all) appears somewhere, ignoring case |
form |
one of the site’s forms, on a site’s list and counts |
limit, cursor |
paging |
curl "https://api.seaforms.io/v1/forms/frm_7f3kq2m4xa/submissions?q=maya&limit=10" \ -H "Authorization: Bearer $SEAFORMS_API_KEY"A submission
Section titled “A submission”interface Submission { id: string; // sub_… formId: string; siteId: string; revision: number; state: "pending_payment" | "complete" | "abandoned"; quota: "counted" | "held"; spam: boolean; test: boolean; createdAt: string; path: string[]; // the steps the visitor went through answers: Answers | null; // null while held over the plan's limit labels: Record<string, string>; // display text: option labels, formatted dates and money files: { id: string; field: string; name: string; size: number; type: string; url: string }[]; variables: Record<string, string>; computed: Record<string, string>; tags: string[]; ending: string | null; pricing?: PriceBreakdown; payment?: Payment; booking?: Booking; // the time booked, kept current from the calendar meta: { page: { url: string; title?: string; referrer?: string }; timezone?: string; locale?: string; attribution?: Record<string, string>; country?: string; userAgent?: string }; consent: { field: string; accepted: boolean; textHash: string; at: string }[]; deliveries: { delivered: number; failed: number; pending: number; held: number };}The answers are keyed by each question’s key, and npx seaforms pull writes a type for them.
- Export streams every match. CSV starts with a byte-order mark so Excel opens it correctly, and its cells are escaped against formula injection.
- Spam keeps the same ID, so links already sent in emails keep working.
Caught as spam
Section titled “Caught as spam”What the server couldn’t confirm came from a person (no JavaScript, an unlisted address, a failed human check, sent too fast, a version of the form we never published) is kept for 30 days as a blocked record. It’s never sent on unless someone says it’s not spam.
- GET
/v1/forms/{formId}/blockedsubmissions:read - What was caught as spam on a form, without its answers. Takes
layer,fromandto. - GET
/v1/sites/{siteId}/blockedsubmissions:read - The same across the site, with who it seems to be from and a short summary.
- GET
/v1/blocked/{id}submissions:read - One, with its answers.
- POST
/v1/blocked/{id}/not-spamsubmissions:write - Makes it a submission (
blk_…becomessub_…) and sends it on like any other. - DELETE
/v1/blocked/{id}submissions:write - Deletes it now, rather than after its 30 days.
layer says what caught it: honeypot, too_fast, rate_limit, daily_cap, no_session, not_human, origin or unknown_revision.
Left part way
Section titled “Left part way”- GET
/v1/forms/{formId}/partialssubmissions:read - People who left a form part way. Pro keeps their answers.
- GET
/v1/sites/{siteId}/partialssubmissions:read - The same across the site.
- GET
/v1/forms/{formId}/partials/stepssubmissions:read - How many stopped at each step.
- GET
/v1/partials/{id}submissions:read - One, with what they'd answered.
- DELETE
/v1/partials/{id}submissions:write - Deletes it.
GET /v1/sites/{siteId}/stats and GET /v1/forms/{formId}/stats are on Sites and Forms.
Find and erase a person
Section titled “Find and erase a person”For a data request. It finds every submission holding someone’s email address or phone number, across your sites.
- GET
/v1/peoplepeople:write - Finds what's held on one person, by
emailorphone, across your sites. Owners and admins. - POST
/v1/people/erasurespeople:write - Erases it. Data already sent to other tools isn't reached.
- GET
/v1/people/erasures/{id}people:write - How an erasure went.
ChatGPT is a trademark of OpenAI, and Claude and Claude Code are trademarks of Anthropic. Other product names and logos belong to their owners. None of them makes or endorses Seaforms. Trademarks