Skip to content

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.

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
Terminal window
curl "https://api.seaforms.io/v1/forms/frm_7f3kq2m4xa/submissions?q=maya&limit=10" \
-H "Authorization: Bearer $SEAFORMS_API_KEY"
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.

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, from and to.
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_… becomes sub_…) 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.

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.

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 email or phone, 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.
Was this helpful?

Your answer goes straight to the person who wrote it.

Thanks. We read every note and update the article.

Thanks, that helps us keep these useful.

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