Skip to content

Forms and publishing

A form has three parts, and each changes differently:

Part What it holds How it changes
The draft the form being edited saved as often as you like; visitors never see it
Revisions each published version, which never changes publishing makes a new one; your site needs a pull or a rebuild
The live config what happens after Send works the moment it’s saved, for every revision
GET /v1/formsforms:read
Forms, by site and name. Each with its status and an overview.
POST /v1/formsforms:write
Makes a form: { siteId, name, from? }. from is { template }, { savedTemplate }, { blank: true } or a whole { definition }.
GET /v1/forms/{formId}forms:read
One form.
PATCH /v1/forms/{formId}forms:write
Renames it: { name }.
DELETE /v1/forms/{formId}forms:write
Deletes it, with its submissions and files. Needs ?confirm={formId}. It can be restored for 7 days.
POST /v1/forms/{formId}/restoreforms:write
Brings a deleted form back.
POST /v1/forms/{formId}/copyforms:write
Copies it to another site as a new, unpublished form: { siteId, name? }. Apps and alerts stay behind, because they're per site.
GET /v1/forms/{formId}/statssubmissions:read
Sessions, submissions and how far people got. Takes from and to.

name is lower-case letters, numbers and dashes, unique on its site. It’s what the file is called: contact saves as contact.seaforms.json.

  1. Make the form. With a definition it’s your own whole form, checked as a draft. One that doesn’t parse is 400, and nothing is made.

    Terminal window
    curl -X POST https://api.seaforms.io/v1/forms \
    -H "Authorization: Bearer $SEAFORMS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "siteId": "site_01JC8H2K4M9V6Q3T7X0B5N2R8D", "name": "contact", "from": { "template": "contact" } }'
  2. Read its draft, and note the ETag.

    Terminal window
    curl -i https://api.seaforms.io/v1/forms/frm_7f3kq2m4xa/draft \
    -H "Authorization: Bearer $SEAFORMS_API_KEY"
  3. Publish it, saying which draft you read.

    Terminal window
    curl -X POST https://api.seaforms.io/v1/forms/frm_7f3kq2m4xa/revisions \
    -H "Authorization: Bearer $SEAFORMS_API_KEY" \
    -H 'If-Match: "d-91c2"'

A form with errors answers 422 invalid_document with issues, and one that uses something the site’s plan doesn’t include answers 403 plan_required.

GET /v1/forms/{formId}/draftforms:read
The form being edited, with the checker's issues and an ETag.
PUT /v1/forms/{formId}/draftforms:write
Saves it: { definition, authoring }, with If-Match. Issues never block a save.
Draft
interface Draft {
definition: FormDefinition; // see The form format
authoring: Record<string, unknown>; // the builder's own notes
issues: Issue[]; // the publish checker's errors and warnings
changesSincePublish: number;
updatedAt: string;
updatedBy: string;
}

Issues never block a save: a half-built draft is normal. A body that doesn’t parse as a form is 400, and over 256 kB of definition is 413.

POST /v1/forms/{formId}/revisionsforms:write
Publishes the draft, with If-Match: <draft etag>. Publishing the same draft twice makes one revision.
GET /v1/forms/{formId}/revisionsforms:read
Its published revisions, without their definitions.
GET /v1/forms/{formId}/revisions/{revision}forms:read
One revision with its definition. latest gets the newest: what pull and getForm read.
Revision
interface Revision {
revision: number;
hash: string;
features: string[];
requiredPlan: "free" | "starter" | "pro" | "agency";
warnings: Issue[]; // errors block publishing; warnings don't
publishedAt: string;
publishedBy: string;
size: number;
definition?: FormDefinition; // on publish, one revision and the latest
}

A published revision never changes, so GET …/revisions/{n} is cached for a year.

The live config holds who’s told, which apps get the submission, spam settings, discount codes, redirects and whether the form is open. It’s checked as you save it: one with errors is refused with 422 invalid_document, and warnings come back in issues.

GET /v1/forms/{formId}/liveforms:read
What happens after Send, with an ETag.
PUT /v1/forms/{formId}/liveforms:write
Replaces it, with If-Match. It works at once, for every revision.
PATCH /v1/forms/{formId}/liveforms:write
Changes part of it, with If-Match and Content-Type: application/merge-patch+json.
POST /v1/forms/{formId}/targets/{targetId}/testforms:write
Sends a test to one alert or app, with a sample or { submission }. Naming a submission also needs submissions:read.

Its top-level keys are status, spam, notifications, confirmations, integrations, tags, computed, coupons, redirects, partials, retention, payments, booking and allowedOrigins. The exact shape is in its JSON Schema.

Pausing a form:

Terminal window
curl -X PATCH https://api.seaforms.io/v1/forms/frm_7f3kq2m4xa/live \
-H "Authorization: Bearer $SEAFORMS_API_KEY" \
-H 'If-Match: "l-7a91"' \
-H "Content-Type: application/merge-patch+json" \
-d '{ "status": { "state": "paused", "message": "Back on Monday." } }'

Save any form as one of the workspace’s templates and start new forms from it on any site, with from: { savedTemplate: "tpl_…" }. A template is a copy: changing the form afterwards leaves it as it was. Who’s emailed and where submissions go are per site, so each new form sets them up.

GET /v1/templatesforms:read
Your workspace's own templates.
POST /v1/templatesforms:write
Saves a form's draft as a template: { formId, name }. Agency.
GET /v1/templates/{id}forms:read
One template, with its definition.
PATCH /v1/templates/{id}forms:write
Renames it: { name }. Agency.
DELETE /v1/templates/{id}forms:write
Deletes it. Forms made from it keep everything.

A key for one site gets 403: templates belong to the workspace. A workspace holds up to 100.

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