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
siteandname. Each with its status and an overview. - POST
/v1/formsforms:write - Makes a form:
{ siteId, name, from? }.fromis{ 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
fromandto.
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.
Making and publishing one
Section titled “Making and publishing one”-
Make the form. With a
definitionit’s your own whole form, checked as a draft. One that doesn’t parse is400, 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" } }' -
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" -
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.
The draft
Section titled “The draft”- 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 }, withIf-Match. Issues never block a save.
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.
Revisions
Section titled “Revisions”- 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.
latestgets the newest: whatpullandgetFormread.
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.
What happens after Send
Section titled “What happens after Send”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-MatchandContent-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 needssubmissions: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:
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." } }'Your own templates
Section titled “Your own templates”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.
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