This is the abridged developer documentation for Seaforms # Your forms, in your own code. > Put Seaforms forms in a site built with code. The React package for React, Next.js, React Router and Astro, the seaforms CLI, signed webhooks, the API, the form format and the MCP connector for AI tools. # Introduction > What a site built with code can do with Seaforms. Draw a published form in your page with the React package, pull it with the CLI or fetch it while you build, get each submission by webhook, and work with your forms through the API or an AI tool. Seaforms is a form builder. You, a colleague or a client build a form in the app at [app.seaforms.io](https://app.seaforms.io) and publish it. These docs are for the developer who puts that form in a site built with code: React, Next.js, Astro, or a site an AI tool built. ## How a form gets to your page A published form is a file: its questions, steps, logic and thank-yous as JSON, such as `src/forms/contact.seaforms.json`. Your site reads it while it builds, and `@seaforms/react` draws it. * **In your page’s HTML.** The form renders on your server as a real `
`. It works before JavaScript loads, then steps, logic and inline errors take over once it does. * **No shift.** Every step, message and price line has its room from the start, so nothing on the page moves. * **Your site’s look.** It ships as plain, accessible HTML that takes your CSS, or with our optional finished style. * **Nothing fetched to draw it.** The form’s structure is in your build. A visitor’s browser talks to Seaforms only to send. You get the file one of two ways: 1. **Pull it.** `npx seaforms pull` saves every published form of your site as a file, with its TypeScript types. Commit them, and pull again after each publish. 2. **Fetch it while you build.** `getForm` from `@seaforms/react/server` fetches a form’s latest published version with an API key. Use it when someone else edits the form: they publish, and your next build has it. ## What happens after Send Who’s emailed, which apps get the submission, spam settings and whether the form is open all live on our server. They change the moment someone saves them in the app, with no new file and no rebuild. Only changes to the questions, steps and logic need a publish. ## What else there is * **[Webhooks](/webhooks/):** each submission posted to your endpoint as JSON, signed so your code can tell it came from us. * **[The API](/api/):** read submissions, mark spam, publish forms and change their settings from your own scripts, with an API key that does only what you tick. * **[The MCP connector](/mcp/):** Claude Code, Cursor, VS Code, ChatGPT, Claude or any app that supports MCP can make and publish forms for you, on every plan. * **[The form format](/format/):** what’s in a form’s file, and its JSON Schema. ## Where to go next [Quickstart](/quickstart/)A published form on a page of your site, in about ten minutes. [Set up with AI](/set-up-with-ai/)Hand these docs to your coding agent. [Next.js](/react/nextjs/)A form in the App Router, from its file or fetched while you build. [React Router](/react/react-router/)A form in a Framework mode route, from its file or fetched while you build. [Astro](/react/astro/)A form in an Astro page, with or without its script. # Quickstart > Put a published Seaforms form on a page of your React, Next.js, React Router or Astro site. Add the site, publish a form, pull it into your code, and show it with one component. You need Node 22 or later, a project on React 18.2 or later (Next.js, React Router in Framework mode, Astro, or React on its own), and a free Seaforms account at [app.seaforms.io](https://app.seaforms.io). 1. **Add your site in the app.** Go to **Settings**, then **Sites**. Under **A site built with code**, choose **Add it**, give it a name and its address, such as `https://northwind.co`, and choose **Add the site**. 2. **Build a form and publish it.** In **Forms**, choose **New form**. Start from a template, a description or a blank form, then choose **Publish**. Your code only ever sees published forms. 3. **Install the package** in your project. * npm ```sh npm install @seaforms/react ``` * pnpm ```sh pnpm add @seaforms/react ``` * yarn ```sh yarn add @seaforms/react ``` * bun ```sh bun add @seaforms/react ``` 4. **Sign in and pull your forms.** From your project’s folder: * npm ```sh npx seaforms login npx seaforms pull ``` * pnpm ```sh pnpm dlx seaforms login pnpm dlx seaforms pull ``` * yarn ```sh yarn dlx seaforms login yarn dlx seaforms pull ``` * bun ```sh bunx seaforms login bunx seaforms pull ``` `login` opens Seaforms in your browser to approve it. `pull` saves each published form of the site in `src/forms` (or `forms` when there’s no `src`), with its types beside it: ```console $ npx seaforms pull Northwind's forms, into src/forms: ✔ contact revision 3, saved Rebuild and deploy your site to put the change on its pages. ``` The first time, it asks which site this project is (or picks your only one) and saves the answer in `seaforms.json`. Commit `seaforms.json` and the form files. 5. **Show the form on a page.** * Next.js app/contact/page.tsx ```tsx import { Form } from "@seaforms/react"; import contact from "@/forms/contact.seaforms.json"; export default function ContactPage() { return (

Get in touch

); } ``` `Form` is a client component, so a server page can use it as it is. Next.js renders it into the page’s HTML. * React Router In Framework mode. A new project has no `src` folder, so `pull` saves to `forms`: app/routes/contact.tsx ```tsx import { Form } from "@seaforms/react"; import contact from "../../forms/contact.seaforms.json"; export default function ContactPage() { return (

Get in touch

); } ``` React Router renders the form into the page’s HTML, on each visit or at build, and it wakes once its script loads. * Astro Add Astro’s React integration if your project doesn’t have it: ```sh npx astro add react ``` src/pages/contact.astro ```astro --- import { Form } from "@seaforms/react"; import contact from "../forms/contact.seaforms.json"; ---

Get in touch

``` `client:load` draws the form in the HTML and wakes it as the page loads. See [Astro](/react/astro/) for `client:visible` and pages with no script at all. * React src/Contact.tsx ```tsx import { Form } from "@seaforms/react"; import contact from "./forms/contact.seaforms.json"; export function Contact() { return ; } ``` Render it on the server where you can, so the form is in the page’s HTML before JavaScript loads. A page drawn only in the browser still works, but shows nothing until its script runs. 6. **Add your site’s addresses.** In the app, go to **Settings**, then **Site details**, and add every address the site is served from under **Addresses**, such as `https://northwind.co` and `https://www.northwind.co`. A submission from an address that isn’t on the list is still kept, but as spam, so a copied form can’t fill your inbox. 7. **Try it on your computer.** Make a dev token under **Dev tokens** in **Site details**, and pass it while you work: Your page ```tsx ``` On `localhost`, answers sent with it are tests: kept apart from real ones and never counted against your plan. See [Try it on your computer](/react/testing/). ## The file you pulled `src/forms/contact.seaforms.json` holds the form’s questions, steps and logic. You never edit it: change the form in the app, publish, and pull again. src/forms/contact.seaforms.json ```json { "schemaVersion": 1, "id": "frm_7f3kq2m4xa", "revision": 3, "locale": "en-AU", "timezone": "Australia/Adelaide", "presentation": { "mode": "steps", "progress": { "bar": false, "time": true }, "labels": { "next": "Continue", "back": "Back", "submit": "Send message" }, "estimatedSeconds": 60, "requiredMarker": "optional-label", "badge": false }, "steps": [ { "id": "get-in-touch", "title": "Get in touch", "blocks": [ { "kind": "field", "key": "name", "label": "Name", "placeholder": "Maya Chen", "required": true, "autocomplete": "name", "type": "text" }, { "kind": "field", "key": "email", "label": "Email", "placeholder": "maya@northwind.co", "required": true, "autocomplete": "email", "type": "email" }, { "kind": "field", "key": "topic", "label": "What’s it about?", "required": true, "type": "choice", "display": "chips", "options": [ { "value": "sales", "label": "Sales" }, { "value": "support", "label": "Support" }, { "value": "press", "label": "Press" }, { "value": "something-else", "label": "Something else" } ] }, { "kind": "field", "key": "message", "label": "Message", "placeholder": "How can we help?", "required": true, "type": "textarea" } ] } ], "endings": [ { "id": "thanks", "title": "Thanks, {name}.", "body": "Your message is with the right person. We usually reply the same day." } ], "features": [], "initial": { "hidden": [], "alwaysRequired": [ "name", "email", "topic", "message" ] }, "hash": "3096824560e56c78" } ``` ## Next * [Next.js](/react/nextjs/), [React Router](/react/react-router/) or [Astro](/react/astro/): fetch the form while your site builds instead, so a client’s publish needs no pull. * [Styling](/react/styling/): your own classes, or our finished look. * [Webhooks](/webhooks/): each submission at your own endpoint. # Set up with AI > Hand these docs to a coding agent such as Claude Code or Cursor and let it put your Seaforms forms in your site. The llms.txt files, and a prompt for Next.js, React Router and Astro. Putting a form in a site is one package, two commands and a component, which makes it a good job for a coding agent. These docs are published in a form an agent can read in one go. ## The files an agent reads | File | What it holds | | ------------------------------------ | --------------------------------------------------------------------------- | | [`/llms.txt`](/llms.txt) | A short map of these docs, with links. | | [`/llms-full.txt`](/llms-full.txt) | Every page in one file. Point an agent here when you want it to write code. | | [`/llms-small.txt`](/llms-small.txt) | The same, trimmed for a smaller context. | ## A prompt for your framework Copy one and paste it into Claude Code, Cursor or any coding agent. Publish the form in the app first: an agent only ever sees published forms. * Next.js Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this Next.js (App Router) project. Run npx seaforms login (I'll approve it in my browser), then npx seaforms pull to save my published forms in src/forms with their types. Then add the contact form to app/contact/page.tsx with the Form component. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` * React Router Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this React Router (Framework mode) project. Run npx seaforms login (I'll approve it in my browser), then npx seaforms pull to save my published forms in forms with their types. Then add the contact form to app/routes/contact.tsx with the Form component. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` * Astro Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this Astro project. Run npx seaforms login (I'll approve it in my browser), then npx seaforms pull to save my published forms in src/forms with their types. Then add the contact form to src/pages/contact.astro with the Form component and client:load. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` ### When a client edits the form If someone else publishes the form’s changes, have the agent fetch it while the site builds instead of keeping its file. Put your form’s ID in place of ``, and set `SEAFORMS_API_KEY` yourself (an [API key](/react/#the-key) that can only read forms): * Next.js Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this Next.js (App Router) project. Fetch the form while the site builds with getForm from @seaforms/react/server. Its ID is . The API key is in the SEAFORMS_API_KEY environment variable: read it from there and never write a key into the code. Then show the form on app/quote/page.tsx, checking for a newly published version at most once an hour. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` * React Router Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this React Router (Framework mode) project. Fetch the form while the site builds with getForm from @seaforms/react/server. Its ID is . The API key is in the SEAFORMS_API_KEY environment variable: read it from there and never write a key into the code. Then show the form on app/routes/quote.tsx, calling getForm in the route's loader, and add /quote to prerender in react-router.config.ts. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` * Astro Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this Astro project. Fetch the form while the site builds with getForm from @seaforms/react/server. Its ID is . The API key is in the SEAFORMS_API_KEY environment variable: read it from there and never write a key into the code. Then show the form on src/pages/quote.astro, with the key read through astro:env as a server secret. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` ## Let the agent build the form too With the [MCP connector](/mcp/), a coding tool such as Claude Code or Cursor can make the form itself, publish it and save its file in your code, so you never leave the editor. You choose what it may do when it connects, and it can’t delete anything. ```sh claude mcp add --transport http seaforms https://mcp.seaforms.io/mcp ``` See [Claude Code](/mcp/claude-code/) or [Cursor, VS Code and others](/mcp/other/) for signing it in. # Install the React package > Install @seaforms/react for React, Next.js, React Router and Astro. What it draws, what it sends, its three entry points, and the Content Security Policy it needs. `@seaforms/react` draws a published Seaforms form as part of your page. It needs React 18.2 or later, and works in anything that renders React: Next.js, Astro with its React integration, [React Router](/react/react-router/) in Framework mode, Remix, or a plain React app. * npm ```sh npm install @seaforms/react ``` * pnpm ```sh pnpm add @seaforms/react ``` * yarn ```sh yarn add @seaforms/react ``` * bun ```sh bun add @seaforms/react ``` ContactPage.tsx ```tsx import { Form } from "@seaforms/react"; import contact from "./forms/contact.seaforms.json"; ; ``` `schema` is the [form’s file](/format/), pulled with [`npx seaforms pull`](/cli/) or fetched while your site builds with [`getForm`](#getform). ## What it draws * **A real HTML form, on your server.** It’s in the page’s HTML before any JavaScript loads, with a real `` that posts to Seaforms if scripts never run. See [Without JavaScript](/react/without-javascript/). * **Then it wakes up.** Once its script runs: one step at a time with Continue and Back, questions that appear as they’re answered, errors when they help (when the visitor tries to continue, or leaves a field with a mistake in it), a live price, file uploads, payments and booking. * **Nothing moves.** Every step, error line and price line has its room from the first render, so waking up shifts nothing on the page. * **Keyboard and screen readers.** Enter moves on. Focus goes to the new step’s title, or to the first answer that needs fixing, and both are announced. Anything typed before JavaScript loaded is kept. ## What it sends Nothing is requested from Seaforms until the visitor first touches the form. Then it opens a session with `https://api.seaforms.io`, uploads files as they’re picked, and on Send stores the answers and shows the thank-you in the form’s own space. A dropped connection is retried, and one session stores at most one submission, so a retry never sends twice. Our server checks every answer again against the form, so a visitor can’t skip a required question or change a price by editing the page. ## Entry points | Import | What it is | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `@seaforms/react` | `Form`, the component, and `Parts`, the names of every part you can style. | | `@seaforms/react/server` | [`getForm`](#getform), for code that runs while your site builds. It isn’t in the main entry, so it never reaches a browser bundle. | | `@seaforms/react/theme.css` | Our optional finished look. See [Styling](/react/styling/). | ## getForm `getForm` fetches a form’s latest published version while your site builds, for forms a client or colleague edits. The code for your framework is on the [Next.js](/react/nextjs/), [React Router](/react/react-router/) and [Astro](/react/astro/) pages. * **The same form as the file.** It returns exactly what the form’s file holds, byte for byte what `npx seaforms pull` saves, so the form draws the same either way. * **Still in your page’s HTML.** It runs while the site builds. Nothing is fetched while a visitor’s page loads. * **It stops the build rather than ship a page without its form.** Every problem is a plain message in your build log. ### The key 1. In the app, go to **Settings**, then **API keys**. Only owners and admins of the workspace can make keys. 2. Under **Sites**, choose the form’s site. Under **It can**, leave only **Read forms** ticked. 3. Choose **Make a key**, and copy it. It’s shown once. 4. Set it as `SEAFORMS_API_KEY` where your site builds: your host’s environment variables, and a `.env` file you don’t commit for your own computer. A key for one site can’t see any other, and one that can only read forms can’t change anything. Never put the key in your code, and never in anything a browser loads: `getForm` refuses to run where `window` exists. ### Options getForm ```ts getForm(formId: string, options: GetFormOptions): Promise ``` * `formId`stringrequired The form’s ID, such as `frm_7f3kq2m4xa`: on its page in the app, under its name. See [Your site and form IDs](/ids/). * `apiKey`string | undefinedrequired An API key (`sfk_…`) that can read forms on the form’s site. Pass `process.env.SEAFORMS_API_KEY` as it is: `undefined` stops the build with a message saying which key to make. * `fetchInit`GetFormFetchInit Passed to `fetch` as it is, for your framework’s caching: Next.js’s `next: { revalidate, tags }`, or `cache`. It’s `RequestInit` without `method`, `headers`, `body` and `redirect`, which `getForm` sets itself. * `api`string Another Seaforms server, for testing. Default `https://api.seaforms.io`. The key only goes to `https://` addresses, or to this computer. It asks for the form’s latest published revision, waits up to 30 seconds, and tries once more when Seaforms is out of reach, slow, busy or briefly down. It never follows a redirect, and the key is never in an error message. ### When it stops the build Each problem throws a `SeaformsError` with a `code` and a message worded for a build log. `status` is the HTTP status Seaforms answered with, or `0`. Handling a SeaformsError ```ts import { getForm, SeaformsError } from "@seaforms/react/server"; try { return await getForm("frm_7f3kq2m4xa", { apiKey: process.env.SEAFORMS_API_KEY }); } catch (e) { if (e instanceof SeaformsError && e.code === "not_published") return null; throw e; } ``` | `code` | What happened | | ----------------------------------- | ----------------------------------------------------------------------------------- | | `no_key` | No key was given. | | `dev_token` | It was given a dev token (`sfd_…`), which is only for `localhost`. | | `bad_key` | The key has a space or a line break in it: copy it again. | | `bad_id` | The ID isn’t a form’s ID, or the key was passed where the ID goes. | | `browser` | It ran where `window` exists. Call it where your site builds. | | `unsafe_address` | `api` isn’t `https://`, or has a user name or password in it. | | `unauthenticated` | Seaforms didn’t accept the key: revoked, or copied only in part. | | `forbidden` | The key can’t read forms. | | `workspace_closed` | The workspace was deleted. For 7 days an owner can restore it. | | `not_found` | No form with that ID that this key can see: check the key’s site. | | `not_published` | The form hasn’t been published yet. | | `cant_draw` | A newer Seaforms published it than this package can draw: update `@seaforms/react`. | | `rate_limited` | Too many requests with this key. Wait a minute. | | `unavailable`, `network`, `timeout` | Seaforms couldn’t be reached, after one more try. | | `redirect` | Something answered with a redirect, which isn’t followed. | | `unreadable`, `refused` | Seaforms sent something unexpected, or refused for another reason. | ## Content Security Policy If your site sends a `Content-Security-Policy` header, allow Seaforms’ two hosts: Content-Security-Policy ```http connect-src 'self' https://api.seaforms.io; frame-src 'self' https://forms.seaforms.io; ``` `api.seaforms.io` takes the answers and files. `forms.seaforms.io` holds the human check, a small frame that’s invisible unless Cloudflare asks the visitor for a click. A form that takes a payment also loads Stripe’s own card fields. Add what [Stripe’s Content Security Policy guide](https://docs.stripe.com/security/guide#content-security-policy) lists for Stripe.js. # Astro > Put a Seaforms form on an Astro page with the React integration, from its file or fetched while the site builds with getForm and an astro:env secret. client:load, client:visible or no script at all. ## Install Add Astro’s React integration if your project doesn’t have it, then the package: ```sh npx astro add react ``` * npm ```sh npm install @seaforms/react ``` * pnpm ```sh pnpm add @seaforms/react ``` * yarn ```sh yarn add @seaforms/react ``` * bun ```sh bun add @seaforms/react ``` ## Add the form There are two ways, and both put the form in your page’s HTML. Pick by who changes it: * **From the form’s file** if you change the form yourself. A pull shows up in your diff, and a build never depends on Seaforms answering. * **Fetched at build** if a client or colleague changes it. They publish in the app and your next build has it, with no file to pull or commit. - From the form's file Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this Astro project. Run npx seaforms login (I'll approve it in my browser), then npx seaforms pull to save my published forms in src/forms with their types. Then add the contact form to src/pages/contact.astro with the Form component and client:load. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` Save your published forms into the project with [`npx seaforms pull`](/cli/), then import one: * astro.config.mjs * seaforms.json which site this project is src/pages/contact.astro ```astro --- import { Form } from "@seaforms/react"; import contact from "../forms/contact.seaforms.json"; ---

Get in touch

``` - Fetched at build Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this Astro project. Fetch the form while the site builds with getForm from @seaforms/react/server. Its ID is . The API key is in the SEAFORMS_API_KEY environment variable: read it from there and never write a key into the code. Then show the form on src/pages/quote.astro with client:load, reading the key through astro:env. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` [Make an API key](/react/#the-key) for the form’s site that can only read forms, and set it where your site builds: .env ```sh SEAFORMS_API_KEY=sfk_… ``` Keep it a secret with `astro:env`, which reads it while the build runs and never writes it into the built code (`import.meta.env` would): astro.config.mjs ```diff +import { defineConfig, envField } from "astro/config"; import react from "@astrojs/react"; export default defineConfig({ integrations: [react()], +env: { +schema: { SEAFORMS_API_KEY: envField.string({ context: "server", access: "secret" }) }, +}, }); ``` src/pages/quote.astro ```astro --- import { Form } from "@seaforms/react"; import { getForm } from "@seaforms/react/server"; import { SEAFORMS_API_KEY } from "astro:env/server"; const quote = await getForm("frm_7f3kq2m4xa", { apiKey: SEAFORMS_API_KEY }); --- ``` Astro fetches the form when it builds the page, so build again once a change is published: a deploy hook on your host does it in one click. Keep the form on a page Astro builds ahead, which is the default. A page rendered on each visit (`export const prerender = false`) would ask Seaforms every time. Its options, and every error that stops a build, are in the [`getForm` reference](/react/#getform). ## Which directive Astro renders the form into the page’s HTML whatever you choose. The directive decides when it wakes up. | Directive | When to use it | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client:load` | The default. It wakes as the page loads. Use it on every page of a form that offers **Save and finish later**: the emailed link’s key leaves the address bar only once the script runs. | | `client:visible` | A form further down the page. It wakes when it scrolls into view. | | none, with `static` | A page that loads no script. Every step shows on one page, with one Send at the end, and the thank-you comes from our server. See [Without JavaScript](/react/without-javascript/). | src/pages/contact.astro ```astro ``` Not client:idle Until the browser is idle, a multi-step form’s **Continue** button does nothing. Use `client:load` or `client:visible`. ## Our finished look Import it once, in a layout: src/layouts/Base.astro ```astro --- import "@seaforms/react/theme.css"; --- ``` See [Styling](/react/styling/) for its variables, or your own classes instead. ## Checked in a real build What this page promises (in the HTML, works before JavaScript, no shift, keyboard and screen readers) is checked by our tests in real Chrome on an Astro site, on all 16 templates. # The Form component > Every prop of Seaforms' Form component for React, what its callbacks receive, the analytics events it fires, and filling answers in from the page's link. ContactPage.tsx ```tsx import { Form } from "@seaforms/react"; import contact from "./forms/contact.seaforms.json"; console.log(submissionId, ending)} />; ``` `Form` is a client component (`"use client"`), so a Next.js server component can render it as it is. ## Props * `schema`FormDefinitionrequired The form’s file: `import contact from "./forms/contact.seaforms.json"`, or what [`getForm`](/react/#getform) returns. A file this version of the package can’t draw shows “This form needs an update to display” instead of a broken form: update `@seaforms/react`. * `className`string A class for the `` element. * `classNames`Partial\> Your classes, keyed by part: `{ input: "h-11 rounded-lg border px-3", "button-submit": "btn btn-primary" }`. Every element also carries `data-sf=""`. See [Styling](/react/styling/). * `headingLevel`2 | 3 | 4 The heading level for step titles and thank-yous. Default `2`. Use `3` when the form sits under your page’s own `

`. * `testToken`string A dev token (`sfd_…`) from the app, for trying the form on `localhost`: answers are kept as tests, apart from real ones and never counted against your plan. Our server ignores it anywhere else. See [Try it on your computer](/react/testing/). * `onStep`(change: { stepId, index, direction }) => void The visitor moved to another step. `direction` is `"forward"` or `"back"`. * `onError`(errors: { stepId, fields }) => void The visitor tried to continue or send with answers that need fixing. `fields` lists their keys. * `onSubmitted`(result: { submissionId, ending }) => void The answers were stored. `submissionId` is the `sub_…` ID, `ending` the ID of the thank-you that showed. Called before any redirect the form’s settings make. * `static`boolean For a page that never loads the component’s script (Astro without a `client:` directive). The form is drawn the way it works without JavaScript: every step on one page, one Send at the end. Leave it off when the form is hydrated. See [Without JavaScript](/react/without-javascript/). * `instance`string Only for two copies of the same form on one page: a suffix that keeps their element IDs apart, such as `instance="footer"`. * `apiBase`string Where the form sends. Default `https://api.seaforms.io`. You don’t need it. ## The answers’ types `npx seaforms pull` writes each form’s types beside its file, so the callbacks can be typed: ContactPage.tsx ```tsx import type { ContactEnding, ContactStep } from "./forms/contact.seaforms"; track(stepId as ContactStep)} onSubmitted={({ ending }) => ending as ContactEnding} />; ``` See [Types for your answers](/cli/types/). ## Analytics events The form fires five events, each a DOM event on the `` (it bubbles) and a `window.dataLayer` push for Google Tag Manager. They carry IDs, never answers. | DOM event | `dataLayer` event | When | `detail` | | ----------------- | ----------------- | --------------------------------- | ------------------------------ | | `seaforms:view` | `seaforms_view` | the form is on the page and awake | `{ formId, revision }` | | `seaforms:start` | `seaforms_start` | the first answer | `{ formId, revision }` | | `seaforms:step` | `seaforms_step` | each step change | `{ stepId, index, direction }` | | `seaforms:error` | `seaforms_error` | an answer needs fixing | `{ stepId, fields }` | | `seaforms:submit` | `seaforms_submit` | the answers were stored | `{ submissionId, ending }` | A `dataLayer` push puts the `detail` under `seaforms`. On Send it also pushes Google Analytics’ `generate_lead`, with the total and its currency when the form has a price. analytics.ts ```ts document.addEventListener("seaforms:submit", (event) => { const { submissionId } = (event as CustomEvent<{ submissionId: string }>).detail; }); ``` ## Answers from the link A question can be filled in from the page’s address, such as `?plan=pro`, when the form’s builder turned that on for it. It’s filled in as the script starts, never over what the visitor already typed, and doesn’t count as them starting the form. Nothing to set on the component. ## Save and finish later When the form offers **Save and finish later**, the visitor can email themselves a link to their answers. The link opens your page with a key after `#`, and the form takes it out of the address bar the moment its script runs. So on every page the form is on, load its script with the page: in Astro, `client:load`, not `client:visible`. # Next.js > Put a Seaforms form on a Next.js App Router page, from its file or fetched while the site builds with getForm, with revalidate, tags and Cache Components. ## Install * npm ```sh npm install @seaforms/react ``` * pnpm ```sh pnpm add @seaforms/react ``` * yarn ```sh yarn add @seaforms/react ``` * bun ```sh bun add @seaforms/react ``` ## Add the form There are two ways, and both put the form in your page’s HTML. Pick by who changes it: * **From the form’s file** if you change the form yourself. A pull shows up in your diff, and a build never depends on Seaforms answering. * **Fetched at build** if a client or colleague changes it. They publish in the app and Next.js picks it up, with no file to pull or commit. - From the form's file Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this Next.js (App Router) project. Run npx seaforms login (I'll approve it in my browser), then npx seaforms pull to save my published forms in src/forms with their types. Then add the contact form to app/contact/page.tsx with the Form component. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` Save your published forms into the project with [`npx seaforms pull`](/cli/), then import one: * seaforms.json which site this project is app/contact/page.tsx ```tsx import { Form } from "@seaforms/react"; import contact from "@/forms/contact.seaforms.json"; export default function ContactPage() { return (

Get in touch

); } ``` `Form` is a client component, so this server page uses it as it is. Next.js renders the form into the page’s HTML, and it wakes once its script loads. `@/forms` is your `src/forms` folder through the `@/*` path Next.js sets up in `tsconfig.json`; use a relative import if your project has no such path. The import fails in TypeScript? Turn on `"resolveJsonModule": true` in `tsconfig.json`. New Next.js projects have it on. - Fetched at build Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this Next.js (App Router) project. Fetch the form while the site builds with getForm from @seaforms/react/server. Its ID is . The API key is in the SEAFORMS_API_KEY environment variable: read it from there and never write a key into the code. Then show the form on app/quote/page.tsx, checking for a newly published version at most once an hour. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` [Make an API key](/react/#the-key) for the form’s site that can only read forms, and set it where your site builds: .env.local ```sh SEAFORMS_API_KEY=sfk_… ``` app/quote/page.tsx ```tsx import { Form } from "@seaforms/react"; import { getForm } from "@seaforms/react/server"; export default async function QuotePage() { const quote = await getForm("frm_7f3kq2m4xa", { apiKey: process.env.SEAFORMS_API_KEY, fetchInit: { next: { revalidate: 3600, tags: ["seaforms:frm_7f3kq2m4xa"] } }, }); return ; } ``` * **`revalidate: 3600`:** the page is built ahead, then checks for a newly published version at most once an hour. If Seaforms can’t be reached then, Next.js keeps the page it has. * **A tag** lets your own route handler or server action refresh it sooner, with `revalidateTag("seaforms:frm_7f3kq2m4xa", "max")`. * **A static export** (`output: "export"`) gets the form at each `next build`. **With Cache Components** (`cacheComponents: true`), call `getForm` inside a cached function. Without one, Next.js stops the build (“uncached data during prerendering”), and wrapping the form in `` instead would draw a placeholder before it, which moves the page. app/quote/page.tsx ```tsx import { cacheLife, cacheTag } from "next/cache"; import { Form } from "@seaforms/react"; import { getForm } from "@seaforms/react/server"; async function quoteForm() { "use cache"; cacheLife("hours"); cacheTag("seaforms:frm_7f3kq2m4xa"); return getForm("frm_7f3kq2m4xa", { apiKey: process.env.SEAFORMS_API_KEY }); } export default async function QuotePage() { return ; } ``` Its options, and every error that stops a build, are in the [`getForm` reference](/react/#getform). ## Our finished look Import its stylesheet once, in your root layout: app/layout.tsx ```diff +import "@seaforms/react/theme.css"; ``` See [Styling](/react/styling/) for its variables, or your own classes instead. ## When it’s sent Use `onSubmitted` in a client component of your own to do something once the answers are stored: app/contact/contact-form.tsx ```tsx "use client"; import { useRouter } from "next/navigation"; import { Form } from "@seaforms/react"; import contact from "@/forms/contact.seaforms.json"; export function ContactForm() { const router = useRouter(); return router.refresh()} />; } ``` Most forms need nothing here: the thank-you shows in the form’s own space, and a redirect after Send is a setting in the app. ## Checked in a real build What this page promises (in the HTML, works before JavaScript, no shift) is checked by our tests in a real Next.js build, on all 16 templates. # React Router > Put a Seaforms form on a React Router page in Framework mode, from its file or fetched while the site builds with getForm on a pre-rendered route. ## Install * npm ```sh npm install @seaforms/react ``` * pnpm ```sh pnpm add @seaforms/react ``` * yarn ```sh yarn add @seaforms/react ``` * bun ```sh bun add @seaforms/react ``` This needs Framework mode Framework mode draws your page on a server or at build, which puts the form in its HTML. With `ssr: false` and no `prerender` it draws in the browser instead, and so do Declarative and Data mode unless you’ve set up server rendering yourself. There the form isn’t in your page’s HTML, so it can’t work before JavaScript, and we can’t promise that nothing moves as it appears. ## Add the form There are two ways, and both put the form in your page’s HTML. Pick by who changes it: * **From the form’s file** if you change the form yourself. A pull shows up in your diff, and a build never depends on Seaforms answering. It works on server-rendered and pre-rendered routes. * **Fetched at build** if a client or colleague changes it. They publish in the app and your next build has it, with no file to pull or commit. It belongs on pre-rendered routes only. - From the form's file Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this React Router (Framework mode) project. Run npx seaforms login (I'll approve it in my browser), then npx seaforms pull to save my published forms in forms with their types. Then add the contact form to app/routes/contact.tsx with the Form component. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` Save your published forms into the project with [`npx seaforms pull`](/cli/), then import one. A new React Router project has no `src` folder, so they go in `forms`: * react-router.config.ts * seaforms.json which site this project is app/routes/contact.tsx ```tsx import { Form } from "@seaforms/react"; import contact from "../../forms/contact.seaforms.json"; export default function ContactPage() { return (

Get in touch

); } ``` React Router renders the form into the page’s HTML, on each visit or at build, and it wakes once its script loads. The import fails in TypeScript? Turn on `"resolveJsonModule": true` in `tsconfig.json`. - Fetched at build Hand this to your coding agent ``` Read https://developer.seaforms.io/llms-full.txt. Install @seaforms/react in this React Router (Framework mode) project. Fetch the form while the site builds with getForm from @seaforms/react/server. Its ID is . The API key is in the SEAFORMS_API_KEY environment variable: read it from there and never write a key into the code. Then show the form on app/routes/quote.tsx, calling getForm in the route's loader, and add /quote to prerender in react-router.config.ts. Use only the components, functions and commands that file lists, and don't edit the .seaforms.json files. ``` [Make an API key](/react/#the-key) for the form’s site that can only read forms, and set it where your site builds: .env ```sh SEAFORMS_API_KEY=sfk_… ``` List the page in `prerender`, so its loader runs while the site builds: react-router.config.ts ```diff import type { Config } from "@react-router/dev/config"; export default { +prerender: ["/quote"], } satisfies Config; ``` app/routes/quote.tsx ```tsx import { Form } from "@seaforms/react"; import { getForm } from "@seaforms/react/server"; import type { Route } from "./+types/quote"; export async function loader() { const quote = await getForm("frm_7f3kq2m4xa", { apiKey: process.env.SEAFORMS_API_KEY }); return { quote }; } export default function QuotePage({ loaderData }: Route.ComponentProps) { return ; } ``` React Router runs the loader once, when it builds the page, and the form goes into the page’s HTML. The key stays in the build: it’s in nothing a browser loads. Build again once a change is published: a deploy hook on your host does it in one click. Keep getForm on pre-rendered routes A loader on a route that isn’t in `prerender` runs on every visit, so `getForm` would call our API on each page view. Forms aren’t meant to be fetched while a visitor waits. On a server-rendered route, use the form’s file. Its options, and every error that stops a build, are in the [`getForm` reference](/react/#getform). ## Our finished look Import its stylesheet once, in your root route: app/root.tsx ```diff +import "@seaforms/react/theme.css"; ``` See [Styling](/react/styling/) for its variables, or your own classes instead. ## Checked in a real build What this page promises is checked by our tests in real Chrome on a React Router 8.5 site in Framework mode, on all 16 templates, on a server-rendered page and on a pre-rendered one. The form is in the HTML, shows and posts without JavaScript, wakes with no hydration errors and no layout shift, and its steps work. `getForm` is checked in a real build with a test key, which ends up in nothing a browser loads. # Styling > Style a Seaforms form in React, Next.js, React Router or Astro your way. Our finished theme.css and its variables, or your own classes on every part with classNames and data-sf. The form ships as plain, accessible HTML. You choose who owns its look: our finished style, or your site’s own CSS. ## Our finished look Your root layout ```ts import "@seaforms/react/theme.css"; ``` * **It takes your page’s font, text size and text colour.** Every grey is mixed from that colour, so it reads right on light and dark sites, and every size is relative to the form’s text. * **It holds its ground.** Rules your site writes for every input, button or label (Bootstrap, Pico, a theme) stop at the form’s edge. Fonts and colours still flow in. * **Make it yours with variables**, set on any selector. They sit at zero weight, so yours always win: src/styles/forms.css ```css [data-sf="form"] { --sf-accent: #0ea5e9; --sf-on-accent: #fff; --sf-radius: 0.5em; --sf-control-height: 3em; } ``` | Variable | Default | What it sets | | --------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------- | | `--sf-accent` | `#2563eb` | buttons, picked options, focus and progress | | `--sf-on-accent` | `#fff` | text on the accent | | `--sf-radius` | `.75em` | corners | | `--sf-control-height` | `2.875em` | fields and buttons | | `--sf-gap` | `.625em` | space between options | | `--sf-field` | a 4% tint of your text colour | a field’s fill | | `--sf-field-line` | a 20% tint | a field’s border | | `--sf-line`, `--sf-line-strong` | 20% and 34% tints | borders and dividers | | `--sf-muted` | 66% of your text colour | help text and progress | | `--sf-placeholder` | from `--sf-muted` | placeholders | | `--sf-danger` | a red leaning toward your text colour | errors, readable on light and dark | | `--sf-title-font`, `--sf-title-size`, `--sf-title-weight` | your font, `1.25em`, `650` | step titles and thank-yous | | `--sf-title-tracking`, `--sf-title-transform` | `-.01em`, `none` | the same, for headings in capitals or a display face | | `--sf-pay-height` | `22em` | the room kept for Stripe’s card fields | ## Your own styles Leave `theme.css` out, and only the structure ships: layout, the room kept for errors, and the rules that keep the form from shifting. Every element carries `data-sf=""`, and `classNames` puts your classes on any part. * Tailwind ContactForm.tsx ```tsx ``` * CSS forms.css ```css [data-sf="label"] { font-weight: 500; } [data-sf="input"], [data-sf="textarea"] { border: 1px solid #d4d4d8; border-radius: 8px; } [data-sf="error"] { color: #dc2626; } [data-sf="button-submit"] { background: #18181b; color: #fff; } ``` Chips, cards, segmented buttons, stars and steppers are real radio buttons, tick boxes and inputs underneath. Unstyled, they fall back to plain radio buttons and tick boxes, so the form always works with the keyboard, with screen readers and without JavaScript. Keep the room Don’t hide `[data-sf="error"]` until it has text, or change its height when it does. Its room is kept from the start so an error never pushes the page down. Style its colour and size, not whether it’s there. ## Every part New parts are only ever added: renaming or removing one would break your styles, so it counts as a breaking change. `formstepsstepstep-titlestep-descriptionblocksprogressprogress-segmentprogress-textresumescreensscreenquestion-numberintrochoice-keyhintprogress-fillgroupgroup-titlegroup-descriptionfieldlabelrequiredoptionalhelpinputtextareaselectaffixchoiceschoicechoice-inputchoice-labelchoice-descriptionchoice-priceswatchchoice-imageother-inputquantityquantity-buttonquantity-valueratingrating-itemfilefile-dropfile-itembookingbooking-monthbooking-month-namebooking-navbooking-weekdaysbooking-weekdaybooking-daysbooking-daybooking-zonebooking-timesbooking-day-namebooking-time-listbooking-timebooking-notebooking-retrysummarysummary-titlesummary-linesummary-totalsummary-depositsummary-balancereviewreview-itemreview-editpaymentpayment-amountpayment-boxpayment-test-bannerpayment-elementpayment-notepayment-retrycouponcoupon-inputcoupon-buttoncoupon-resulterrorcheck-errornavbutton-backbutton-nextbutton-submitbutton-savesavesave-titlesave-bodysave-inputsave-buttonsave-backsave-noteendingending-titleending-bodycontentdividerimagebadgeclosedturnstilestatus` # Try it on your computer > Send test submissions from localhost with a Seaforms dev token (sfd_…). What a test is, where to keep the token, and why localhost without one lands in Spam. While your site runs on `localhost`, pass the form a dev token. Answers sent with it are tests: kept apart from real ones and never counted against your plan. 1. In the app, go to **Settings**, then **Site details**, and find **Dev tokens**. Your site needs to be one built with code. 2. Give it a name, such as “Maya’s laptop”, and choose **Make a token**. 3. Copy it straight away: it isn’t shown again. 4. Pass it to the form while you work: Your page ```tsx ``` To keep it out of your code, put it in a `.env` file you don’t commit and read it from there, such as `testToken={import.meta.env.PUBLIC_SEAFORMS_DEV_TOKEN}` in Astro. Leave it unset in production: the form needs nothing there. ## What a test is * It’s kept apart from real submissions, and never counted against your plan. * Everything after Send still runs, so you can check it end to end: email alerts (marked as a test), chat apps (`[Test]` before the title), webhooks (`"test": true` in the [body](/webhooks/events/)), the visitor’s thank-you email and newsletter sign-ups. Type your own address in the form’s email question. * A booking made with it books nothing in your calendar. ## The rules * **Only on `localhost`.** Our server ignores a dev token from any other address, so your live site can never send tests by mistake, even if the token ships in its code. * **90 days.** Each token lasts 90 days. **Site details** lists each with when it was made, when it ends and when it was last used. * **Stop one early** with the cross beside it. Anything using it stops at once. # Without JavaScript > What a Seaforms form does when its script never runs. The real HTML form post, how those posts are kept and sent on, the static prop for pages with no script, and how bookings and payments behave. Every Seaforms form is a real HTML form before it’s anything else. If its script never runs (blocked, slow, failed, or a page that loads none), the visitor can still fill it in and send it. The page's HTML ```html … ``` Our server answers the post with a redirect: back to your page with the thank-you showing, to a thank-you page on `forms.seaforms.io`, or to a page listing what needs fixing, with a link back. ## What happens to those posts A post without JavaScript has no session, so our server can’t confirm a person sent it rather than a bot. It’s kept, never dropped, but under **Spam** in the app’s Submissions, and nobody is emailed about it yet. * **Not spam** on one sends it on like any other: email alerts, the visitor’s thank-you email, your apps and webhooks. * The same post from the same visitor within 10 minutes (a refresh, a double-click) is kept once. * Files sent this way aren’t kept. Real visitors almost always have JavaScript, so in practice these are the rare ones, and bots. ## Pages that load no script In Astro without a `client:` directive, or any server rendering without hydration, pass `static`: src/pages/contact.astro ```astro
``` The form is then drawn the way it works without JavaScript: every step on one page, every follow-up question showing, one Send at the end, and the thank-you from our server. A hydrated form leaves `static` off: it draws one step at a time and takes over the moment its script runs, keeping anything typed before. ## Bookings and payments * **A booking question** needs JavaScript to pick a time. Without it, the question says the visitor will pick a time next, and after Send they go to the business’s booking page with their name and email filled in. Booking a time there sends their post on by itself. * **A payment** needs JavaScript, because Stripe’s card fields do. Without it, the visitor is told so, and nobody is charged. # The API > Seaforms' Management API at api.seaforms.io/v1. Make an API key, what each scope allows, your first call, and the conventions every endpoint follows. The Management API lets your own scripts and servers do what the app does: read submissions, mark spam, publish forms and change what happens after Send. GET`https://api.seaforms.io/v1/{resource}` ```sh curl https://api.seaforms.io/v1/sites \ -H "Authorization: Bearer $SEAFORMS_API_KEY" ``` Response ```json { "data": [ { "id": "site_01JC8H2K4M9V6Q3T7X0B5N2R8D", "name": "Northwind", "platform": "npm", "platformSiteId": null, "domains": ["https://northwind.co", "https://www.northwind.co"], "plan": { "plan": "pro", "source": "subscription" }, "createdAt": "2026-11-02T04:12:51Z" } ], "nextCursor": null } ``` ## API keys 1. In the app, go to **Settings**, then **API keys**. Only owners and admins can make keys. 2. Give it a **Name** that says what uses it, such as “Nightly export”. 3. Under **Sites**, choose **Every site** or one. A key for one site can’t see or change any other. 4. Under **It can**, tick only what it needs. 5. Choose **Make a key**, and copy it. It’s shown once, and stored only as a hash. Send it on every request as a bearer token. Keep it on your server or in your build’s environment, never in anything a browser loads. * **A key is limited twice:** by what you ticked, and by the role of the person who made it. It never does more than they can. * **It ends** when you revoke it, when the person who made it leaves the workspace, or when its site is removed. * **No key can make, see or revoke keys.** That’s done in the app. ## Scopes | Scope | In the app | Allows | | ------------------- | ------------------------------ | ------------------------------------------------------------------------- | | `account:read` | every key has it | the workspace, its sites and their usage | | `forms:read` | Read forms | forms, drafts, revisions, live config, connections (masked), recipients | | `forms:write` | Build and publish forms | make, edit and publish forms; edit live config; recipients and dev tokens | | `submissions:read` | Read submissions | submissions, spam, people who left part way, deliveries, exports | | `submissions:write` | Change submissions | mark spam and not spam, delete, resend | | `connections:write` | Change where submissions go | add, change and remove connections | | `payments:write` | Connect a Stripe account | connect a Stripe account for payments | | `people:write` | Find and erase a person’s data | find and erase one person’s data. Owners and admins only. | A missing scope answers `403 forbidden`. Something in another workspace answers `404`, so IDs can’t be probed. ## Who you are * GET `/v1/me` Who this key or sign-in is: the person, the workspace and its plan, their role and what it can do. * POST `/v1/sign-out` Ends the sign-in whose token you send. An API key is revoked in the app instead. ## Conventions * **JSON in and out**, with camelCase names, the same as the [form format](/format/). * **Unknown properties are refused** with `400 bad_request`, so a typo in a script shows up at once. Ignore properties you don’t know in responses: they grow over time. * **Times** are RFC 3339 in UTC, such as `2026-11-12T09:41:07Z`. Dates in answers stay `YYYY-MM-DD`, in the form’s time zone. * **Money** is an integer in minor units plus a currency: `{ "amount": 8250, "currency": "AUD" }` is $82.50. * **Every response** carries `Seaforms-Request-Id`. Quote it when you ask us about a problem. * **The version is in the path.** Within `/v1`, changes only ever add things. ## What’s next * [Errors](/api/errors/), and [Lists, retries and edits](/api/conventions/): how every endpoint behaves. * [Sites](/api/sites/), [Forms and publishing](/api/forms/), [Submissions](/api/submissions/), [Connections and deliveries](/api/connections/). * [Limits](/api/limits/). # Connections and deliveries > The Seaforms API's connection and delivery routes. Connect a webhook, Discord or Teams, rotate a signing secret, send a test, and see and resend each delivery. A connection is a linked account or endpoint that belongs to a site: a webhook address, Discord, Teams or Slack, a Cal.com, Mailchimp or Kit key, or a Stripe account. A form then switches it on in its [live config](/api/forms/#what-happens-after-send). * GET `/v1/connections`forms:read A site's connections, by `site`. Addresses are masked after the host, and secrets never come back. * POST `/v1/connections`connections:write Connects a webhook, Discord, Teams or more. A webhook's signing secret is in this answer only. * GET `/v1/connections/{id}`forms:read One connection, and which forms use it. * GET `/v1/connections/{id}/choices/{kind}`forms:read What can be picked in it, such as Cal.com's `event-types`. * PATCH `/v1/connections/{id}`connections:write Changes `name`, `url` or `headers`. `{ status: "active" }` turns a paused one back on and sends what it held. * DELETE `/v1/connections/{id}`connections:write Removes it. Refused with `409` while a form uses it. * POST `/v1/connections/{id}/test`connections:write Sends a sample, marked as a test. Ten an hour. * POST `/v1/connections/{id}/rotate-secret`connections:write A new signing secret. The old one keeps signing for 24 hours. Connecting a webhook: ```sh curl -X POST https://api.seaforms.io/v1/connections \ -H "Authorization: Bearer $SEAFORMS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "siteId": "site_01JC8H2K4M9V6Q3T7X0B5N2R8D", "provider": "webhook", "name": "My CRM", "url": "https://hooks.northwind.co/seaforms", "headers": { "Authorization": "Bearer my-crm-key" } }' ``` Response ```json { "connection": { "id": "con_01JC8H2K4M7P9X3V5B8N1Q6W2T", "siteId": "site_01JC8H2K4M9V6Q3T7X0B5N2R8D", "provider": "webhook", "name": "My CRM", "status": "active", "url": "https://hooks.northwind.co/•••", "headerNames": ["Authorization"], "createdAt": "2026-11-12T09:41:07Z", "usedBy": [] }, "secret": "whsec_…" } ``` * **The address** must be `https` on port 443, a hostname rather than an IP address, and not one of Seaforms’ own. * **Header values** are write-only. `Host`, `Content-Length`, `Content-Type`, `Transfer-Encoding`, `Connection`, `User-Agent` and any `webhook-*` header are refused. `Authorization` is fine. * **Addresses are credentials.** Discord, Teams and Zapier addresses work for anyone who has them, so they’re stored encrypted and only ever shown up to the host. * **A site holds up to 50 connections.** ## Deliveries One delivery is one target (an email alert, a thank-you email, an app or a webhook) for one submission. * GET `/v1/submissions/{id}/deliveries`submissions:read Where one submission went, and how each try ended. * GET `/v1/forms/{formId}/deliveries`submissions:read A form's deliveries. Takes `status`, `target`, `from` and `to`. * POST `/v1/deliveries/{id}/resend`submissions:write Sends it again. A delivery’s `status` is `pending`, `delivered`, `failed`, `held` or `skipped`. Retries and pausing are on [Retries and repeats](/webhooks/retries/). # Lists, retries and edits > How the Seaforms API pages through lists, makes a POST safe to retry with Idempotency-Key, and keeps two editors from overwriting each other with ETags and If-Match. ## Lists Lists are newest first and paged by cursor: Request ```http GET /v1/forms/frm_7f3kq2m4xa/submissions?limit=50&cursor=sub_01JC8H2K4M7P9X3V5B8N1Q6W2T ``` Response ```json { "data": [ … ], "nextCursor": "sub_01JC7Z4N8K2W6R9T3B5X1M7Q4D" } ``` * `limit` is 25 by default, and 100 at most. * `nextCursor` is `null` on the last page. Pass it back as `cursor`. * Cursors hold steady while new items arrive, so paging never skips or repeats. * Lists don’t include a total. Counts that matter, such as [a site’s submissions](/api/submissions/), have their own route. every-submission.ts ```ts async function* submissions(formId: string) { let cursor: string | null = null; do { const url = new URL(`https://api.seaforms.io/v1/forms/${formId}/submissions`); url.searchParams.set("limit", "100"); if (cursor) url.searchParams.set("cursor", cursor); const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.SEAFORMS_API_KEY}` } }); if (!res.ok) throw new Error(`Seaforms answered ${res.status}`); const page = (await res.json()) as { data: unknown[]; nextCursor: string | null }; yield* page.data; cursor = page.nextCursor; } while (cursor); } ``` ## Retrying a POST Send `Idempotency-Key` on any `POST`, and a retry after a lost response does the work once: ```sh curl -X POST https://api.seaforms.io/v1/forms \ -H "Authorization: Bearer $SEAFORMS_API_KEY" \ -H "Idempotency-Key: 5b0e2c1a-7f34-4d3e-9a61-2f8c6b1d4e90" \ -H "Content-Type: application/json" \ -d '{ "siteId": "site_01JC8H2K4M9V6Q3T7X0B5N2R8D", "name": "contact" }' ``` * Up to 255 characters. A UUID is ideal. * A successful answer is kept for 24 hours. The same key and body gets the same answer again, with `Idempotent-Replayed: true`. * The same key with a different body is `422 idempotency_key_reused`. * A repeat while the first is still running is `409 conflict`, with `Retry-After: 1`. ## Editing safely Two people can have the same form open. So the draft and the live config use ETags: read one, then send its `ETag` back as `If-Match` when you change it. ```sh # Read it, and note the ETag header. curl -i https://api.seaforms.io/v1/forms/frm_7f3kq2m4xa/live \ -H "Authorization: Bearer $SEAFORMS_API_KEY" # Change it, saying which version you read. 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." } }' ``` * A missing `If-Match` is `428 precondition_required`. * A stale one is `412 precondition_failed`, and its body carries the current version, so you can merge and try again: 412 response ```json { "type": "https://developer.seaforms.io/api/errors/#precondition_failed", "status": 412, "code": "precondition_failed", "title": "Someone else saved first", "current": { "etag": "\"l-91c2\"", "document": { "…": "…" }, "updatedAt": "2026-11-12T09:41:07Z", "updatedBy": "Mia" } } ``` ## Rate limits Too many requests answers `429`, always with `Retry-After` in seconds. Wait that long and try again. See [Limits](/api/limits/). # Errors > Every error from the Seaforms API, as an RFC 9457 problem document with a stable code to branch on. Every error is a [problem document](https://www.rfc-editor.org/rfc/rfc9457), with `Content-Type: application/problem+json`: Error response ```json { "type": "https://developer.seaforms.io/api/errors/#validation_failed", "title": "Some answers need fixing", "status": 422, "code": "validation_failed", "detail": "2 answers need fixing.", "errors": { "email": { "key": "invalid_email" }, "budget": { "key": "required" } }, "requestId": "req_01JC8H2K4M7P9X3V5B8N1Q6W2T" } ``` * **`code` is what your program should branch on.** It’s stable. `title` and `detail` are for people, and may change. * `errors` appears on answers that need fixing, keyed by question, each with a message key and its values. * `issues` appears on a draft or live config that won’t go through: the publish checker’s list. * `requestId` is the same as the `Seaforms-Request-Id` header. Quote it when you ask us about a problem. ## Codes | Status | Code | When | | ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | 400 | `bad_request` | Malformed JSON, a wrong type, or a property the endpoint doesn't know. | | 401 | `unauthenticated` | No token, or a bad or ended one. | | 401 | `session_invalid` | A form's session has ended or isn't valid. `@seaforms/react` renews it and tries again by itself. | | 403 | `forbidden` | The key doesn't have the scope, or its maker's role doesn't allow it. | | 403 | `origin_not_allowed` | A checkout from an address that isn't on the site's list. | | 403 | `verification_required` | This needs a confirmed person, and the form's session isn't one. | | 403 | `payment_blocked` | This session had too many failed payments. | | 403 | `plan_required` | The site's plan doesn't include this. Carries `requiredPlan`. | | 403 | `workspace_closed` | The workspace was deleted. For 7 days an owner can restore it, and the key works again. | | 404 | `not_found` | It doesn't exist, was deleted, or is in another workspace. | | 409 | `form_not_open` | The form is paused, closed, scheduled or full. Carries `status`. | | 409 | `price_changed` | A checkout's amount differs from what the visitor saw. Carries the new `pricing` and `payment`. | | 409 | `revision_unknown` | A checkout from a version of the form we never published. | | 409 | `payments_paused` | The form's payments are paused after a spike of failures. | | 409 | `conflict` | The object's state doesn't allow this right now. `detail` says why. | | 412 | `precondition_failed` | `If-Match` is out of date: someone else saved first. Carries `current`. See [Editing safely](/api/conventions/#editing-safely). | | 413 | `payload_too_large` | Over a [size limit](/api/limits/). | | 415 | `unsupported_media_type` | A content type this endpoint doesn't take. | | 422 | `validation_failed` | Answers need fixing. Carries `errors`. | | 422 | `invalid_document` | A draft that won't publish, or a live config with errors. Carries `issues`. | | 422 | `coupon_invalid` | A discount code that isn't valid now. Carries `reason`. | | 422 | `idempotency_key_reused` | The same `Idempotency-Key` with a different body. | | 428 | `precondition_required` | This needs `If-Match`, and it was missing. | | 429 | `rate_limited` | Too many requests. `Retry-After` says when to try again. | | 500 | `server_error` | Our fault. It's safe to retry. | | 503 | `unavailable` | Something we depend on is down. `Retry-After` says when to try again. | # The Form API > What a Seaforms form calls from a visitor's browser at api.seaforms.io/f, how it keeps a lead safe, and why you use the React component rather than call it yourself. The Form API is what a form in a visitor’s browser talks to. [`@seaforms/react`](/react/) calls it for you. It’s here so you know what’s on the wire: for a Content Security Policy, a log, or a look in the network tab. Use the component You don’t need to call these yourself, and a form you build by hand wouldn’t be treated as a person: without a real session, its posts are [kept as spam](/react/without-javascript/#what-happens-to-those-posts). | Endpoint | When | | -------------------------------- | ------------------------------------------------------------------------------------------------- | | `POST /f/{formId}/sessions` | The visitor first touches the form. Opens a session, and says whether the form is open. | | `POST /f/{formId}/validate` | A step needs a check only the server can do, such as a blocked email domain. | | `POST /f/{formId}/partials` | The visitor moves between steps. | | `POST /f/{formId}/uploads` | A file is picked. Then `PUT` its bytes to `/f/{formId}/uploads/{uploadId}` and `POST …/complete`. | | `POST /f/{formId}/check-coupon` | A discount code is applied. Codes are checked here, and never appear in the page. | | `POST /f/{formId}/booking/slots` | The visitor reaches a booking question. Gets the free times. | | `POST /f/{formId}/checkout` | The visitor pays. Our server works out the amount, never the browser. | | `POST /f/{formId}/resume-link` | The visitor asks to save and finish later. | | `POST /f/{formId}` | Send. Also the `` of a post [without JavaScript](/react/without-javascript/). | ## What it promises * **It never breaks.** Its addresses are in published pages, so it only ever gains things. A form published today still works years from now. * **The server is the source of truth.** The browser sends answers, never totals, paths or amounts. The server runs the form’s logic again, and stores its own numbers. * **It never drops a lead.** Anything it can’t confirm came from a person is kept as spam, where **Not spam** sends it on. The only outright refusals are a form that isn’t open, answers the visitor can fix, and a checkout it can’t confirm. * **One session stores one submission,** so a retry after a lost response never sends twice. * **Nothing private reaches the page.** Discount codes, routing, scores and secrets stay on the server. # Forms and publishing > The Seaforms API's form routes. Make a form, edit its draft, publish a revision, change what happens after Send through the live config, and use your own templates. 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 | ## Forms * GET `/v1/forms`forms:read Forms, by `site` and `name`. Each with its status and an overview. * POST `/v1/forms`forms: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}/restore`forms:write Brings a deleted form back. * POST `/v1/forms/{formId}/copy`forms: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}/stats`submissions: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`. ## Making and publishing one 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. ```sh 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`. ```sh 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. ```sh 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 * GET `/v1/forms/{formId}/draft`forms:read The form being edited, with the checker's issues and an `ETag`. * PUT `/v1/forms/{formId}/draft`forms:write Saves it: `{ definition, authoring }`, with `If-Match`. Issues never block a save. Draft ```ts interface Draft { definition: FormDefinition; // see The form format authoring: Record; // 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 * POST `/v1/forms/{formId}/revisions`forms:write Publishes the draft, with `If-Match: `. Publishing the same draft twice makes one revision. * GET `/v1/forms/{formId}/revisions`forms: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 ```ts 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 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}/live`forms:read What happens after Send, with an `ETag`. * PUT `/v1/forms/{formId}/live`forms:write Replaces it, with `If-Match`. It works at once, for every revision. * PATCH `/v1/forms/{formId}/live`forms:write Changes part of it, with `If-Match` and `Content-Type: application/merge-patch+json`. * POST `/v1/forms/{formId}/targets/{targetId}/test`forms: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](/format/json-schema/). Pausing a form: ```sh 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 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/templates`forms:read Your workspace's own templates. * POST `/v1/templates`forms: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. # Limits > The Seaforms API's rate limits and size limits, for the Management API, forms and webhooks. ## Rate limits Per-minute limits are approximate. Over one answers `429 rate_limited`, always with `Retry-After` in seconds. | What | Limit | Per | | ---------------------------------------- | ----------------------------------------------- | -------------- | | The Management API | 300 a minute | key or sign-in | | Export | 10 a minute | key or sign-in | | Send a test to a form’s alert or app | 10 a minute | form | | Send a test to a connection | 10 an hour, and 30 an hour across the workspace | connection | | Any call with a key, before it’s checked | 1,200 a minute | IP address | | AI tools at `/mcp` | each tool’s calls count toward the 300 a minute | connection | ## What a form takes | What | Limit | Per | | -------------------- | --------------------------------------------- | ------------------- | | Send | 5 a minute, or 30 on a form set up for events | IP address and form | | Opening a session | 20 a minute | IP address and form | | Uploads | 20 a minute, 200 MB in all | session | | Discount code checks | 10 a session, 30 an hour | session, IP address | | Payment attempts | 10 a minute, 3 failed payments | session | ## Sizes | What | Limit | | ----------------------------------------- | ----------------------------------------- | | A form’s definition (a draft) | 256 kB, and 1 MB with the builder’s notes | | A live config | 256 kB | | A JSON body to the Form API | 1 MB | | A post without JavaScript, with its files | 25 MB | | One uploaded file | 25 MB | | A webhook’s body | 1 MB (longer answers are trimmed) | | A body to `/mcp` | 1 MB | | A list | 100 a page | ## Your plan’s allowance | Plan | Submissions a month | Sites | Submissions kept | File storage | | ------- | ------------------- | --------- | ---------------- | ------------ | | Free | 100 | 1 | 30 days | 100 MB | | Starter | 1,000 | 1 | No limit | 5 GB | | Pro | 5,000 | 3 | No limit | 20 GB | | Agency | 25,000 | Unlimited | No limit | 100 GB | # Sites > The Seaforms API's site routes. List and add sites, read usage and stats, and manage who can be emailed and dev tokens. A site is one website on one platform. Its forms share its addresses, its connected apps and its plan. * GET `/v1/sites`account:read The sites this key can see. * POST `/v1/sites`forms:write Adds a site: `{ name, platform, platformSiteId?, domains? }`. A site built with code is `platform: "npm"`. * GET `/v1/sites/{siteId}`account:read One site. * PATCH `/v1/sites/{siteId}`forms:write Changes `name` or `domains`. `domains` replaces the whole list. * GET `/v1/sites/{siteId}/usage`account:read This month's submissions and AI drafts against the plan's allowance. * GET `/v1/sites/{siteId}/stats`submissions:read Sessions, submissions, finish rate, paid, booked, top sources and each day's numbers. Takes `from`, `to` and `form`. Site ```ts interface Site { id: string; // site_… name: string; platform: "framer" | "webflow" | "wordpress" | "npm"; // npm: a site built with code platformSiteId: string | null; // the builder's own id for the site domains: string[]; // exact origins, such as "https://northwind.co" plan: { plan: "free" | "starter" | "pro" | "agency"; source: string }; // source: "subscription" unless the site has its own createdAt: string; } ``` `domains` are the addresses the site’s forms take submissions from. A submission from anywhere else is [kept as spam](/react/without-javascript/#what-happens-to-those-posts). Each is a whole origin: scheme and host, no path. ## Who can be emailed Email alerts can go to your team and to any address that has confirmed. Someone who isn’t a member gets a link to confirm first, and nothing is sent to them until they do. * GET `/v1/sites/{siteId}/recipients`forms:read The addresses that can be emailed about submissions, and whether each has confirmed. * POST `/v1/sites/{siteId}/recipients`forms:write Adds an address: `{ email }`. Someone outside your team gets a link to confirm before they're sent anything. * DELETE `/v1/sites/{siteId}/recipients/{recipientId}`forms:write Removes an address. - At most 25 addresses can be waiting to confirm on a site (`409` past that), and 20 new ones can be added per workspace in a day (`429`). - A form’s settings may name an address that’s still waiting. Its emails are skipped until it confirms. ## Dev tokens For [trying forms on `localhost`](/react/testing/). * GET `/v1/sites/{siteId}/dev-tokens`forms:read The site's [dev tokens](/react/testing/), without their values. * POST `/v1/sites/{siteId}/dev-tokens`forms:write Makes one: `{ name }`. The value (`sfd_…`) is in this answer only. * DELETE `/v1/sites/{siteId}/dev-tokens/{id}`forms:write Ends one. # Submissions > The Seaforms API's submission routes. List, filter, search and export submissions, mark spam, read what was caught, see who left part way, and erase a person's data. A submission is either normal or spam. There’s no status to manage. * GET `/v1/forms/{formId}/submissions`submissions:read A form's submissions, newest first. * GET `/v1/sites/{siteId}/submissions`submissions:read Every form's on the site, newest first. Also takes `form`. * GET `/v1/sites/{siteId}/submissions/counts`submissions:read How many there are in each view: `{ all, spam, blocked, unfinished, unfinishedWithDetails }`. * GET `/v1/forms/{formId}/submissions/export`submissions: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}/spam`submissions:write Marks it spam, stops what was still to be sent and stops counting it. * POST `/v1/submissions/{id}/not-spam`submissions: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/bulk`submissions:write `{ action: "spam" | "not-spam" | "delete", ids }`, up to 100. Answers per item, so one failure doesn't stop the rest. ## 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](/api/conventions/#lists) | ```sh curl "https://api.seaforms.io/v1/forms/frm_7f3kq2m4xa/submissions?q=maya&limit=10" \ -H "Authorization: Bearer $SEAFORMS_API_KEY" ``` ## A submission Submission ```ts 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; // display text: option labels, formatted dates and money files: { id: string; field: string; name: string; size: number; type: string; url: string }[]; variables: Record; computed: Record; 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; 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`](/cli/types/) 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 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}/blocked`submissions:read What was caught as spam on a form, without its answers. Takes `layer`, `from` and `to`. * GET `/v1/sites/{siteId}/blocked`submissions: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-spam`submissions: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`. ## Left part way * GET `/v1/forms/{formId}/partials`submissions:read People who left a form part way. Pro keeps their answers. * GET `/v1/sites/{siteId}/partials`submissions:read The same across the site. * GET `/v1/forms/{formId}/partials/steps`submissions: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. ## Stats `GET /v1/sites/{siteId}/stats` and `GET /v1/forms/{formId}/stats` are on [Sites](/api/sites/) and [Forms](/api/forms/#forms). ## 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/people`people:write Finds what's held on one person, by `email` or `phone`, across your sites. Owners and admins. * POST `/v1/people/erasures`people:write Erases it. Data already sent to other tools isn't reached. * GET `/v1/people/erasures/{id}`people:write How an erasure went. Erasing is for good It can’t be undone, and it doesn’t reach data already sent to other tools, such as your email, CRM or spreadsheet. Remove it there too. # The seaforms command > The seaforms CLI for sites built with code. Sign in, link a project to its site, pull every published form into your code with its TypeScript types, and sign out. Every command and option. `seaforms` saves your site’s published forms in your project as files, each with a TypeScript type for its answers. It needs Node 22 or later, and nothing to install: * npm ```sh npx seaforms login npx seaforms pull ``` * pnpm ```sh pnpm dlx seaforms login pnpm dlx seaforms pull ``` * yarn ```sh yarn dlx seaforms login yarn dlx seaforms pull ``` * bun ```sh bunx seaforms login bunx seaforms pull ``` ## Commands | Command | What it does | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `login` | Shows a page and a code, opens the page in your browser, and waits while you approve it in the app. It signs in to the workspace you approve it for. | | `link` | Chooses which of your sites this project is: your only site built with code is picked for you; with several, it asks. Saves `seaforms.json` at the project's root. Commit it. | | `pull [forms…]` | Saves the site's published forms (or only those named) as `.seaforms.json`, each with `.seaforms.d.ts` beside it. Links first if the project isn't linked. | | `types [files or folders…]` | Writes the types for form files already in the project, such as one downloaded from the app. No sign-in and no network. | | `whoami` | Who you're signed in as, in which workspace, and this project's site. | | `logout` | Ends the sign-in on Seaforms, then forgets it on this computer. | ## Options | Option | With | What it does | | ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `--site ` | link, pull | The site to use (`site_…`), instead of asking. | | `--dir ` | link, pull, types | Where form files go: `src/forms` by default, or `forms` when there's no `src`. Saved in `seaforms.json`, and always inside the project. | | `--no-types` | pull | Pull without writing types. | | `--no-browser` | login | Show the page to open without opening it, for a machine with no browser. | | `--api ` | every command but types | Another Seaforms server, for testing. Also `SEAFORMS_API`. | `npx seaforms help` lists them, and `npx seaforms --version` says which version you have. ## Signing in ```console $ npx seaforms login To sign in, open this page: https://app.seaforms.io/device?user_code=KQWXPLMN and check it shows the code KQWX-PLMN. (It's opening in your browser.) Waiting for you to approve it… Press Ctrl+C to stop. Signed in as maya@northwind.co, in Northwind. Next: npx seaforms pull saves your site's forms in this project. ``` The page shows what’s asking and where from. Approve it in the workspace you want the CLI to work in; you’re emailed that it signed in. * **It can only read.** The CLI asks for nothing but your workspace’s sites and its forms, so its sign-in can’t change anything. * **Kept in your config folder**, never in the project: `~/.config/seaforms/auth.json` (`%APPDATA%\Seaforms` on Windows, or `SEAFORMS_CONFIG_DIR`), readable only by you. It’s never printed. * **It lasts 30 days after you last use it**, 90 at most. Then `login` again. * **`logout` ends it on Seaforms**, not only here. You can also see and end it in the app, under **Settings**, then **Profile**. ## Pulling ```console $ npx seaforms pull Northwind's forms, into src/forms: ✔ contact revision 3, saved · quote revision 7, already up to date – survey not published yet: publish it in the app first Rebuild and deploy your site to put the change on its pages. ``` * **Only published forms.** A form’s draft never reaches your code. * **Byte for byte the app’s download.** A pulled file is exactly what **Download the file for your code** in the app saves, so the two are interchangeable. * **Written only when it changes**, so pulling again leaves git alone. * **Never deleted.** A file whose form was renamed or deleted in the app is pointed out, for you to remove once nothing imports it. * **One form at a time:** `npx seaforms pull contact quote`. ## Which project The project is the nearest folder above you with a `seaforms.json`, `package.json` or `.git`. In a monorepo, run it in the package whose site it is: its `seaforms.json` goes there. ## In CI Set `SEAFORMS_API_KEY` to an API key that can read forms, commit `seaforms.json`, and `npx seaforms pull` needs nothing else. See [In CI](/cli/ci/). # In CI > Pull your published Seaforms forms in a build or CI job with an API key in SEAFORMS_API_KEY, with a GitHub Actions example. In a build or CI job there’s no one to approve a sign-in, so the CLI uses an API key instead. 1. In the app, go to **Settings**, then **API keys**. Choose the site, and under **It can**, leave only **Read forms** ticked. Make the key and copy it. 2. Set it as `SEAFORMS_API_KEY`, a secret in your CI or your host’s build settings. 3. Commit `seaforms.json`, so the CLI knows the site. A key made for one site works without it too. 4. Run `npx seaforms pull` before your build. .github/workflows/deploy.yml ```yaml name: Deploy on: push: branches: [main] workflow_dispatch: jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: { node-version: 22 } - run: npx seaforms pull env: SEAFORMS_API_KEY: ${{ secrets.SEAFORMS_API_KEY }} - run: npm ci && npm run build ``` * **`login` and `logout` refuse while the key is set**, so a CI job never waits on a sign-in. * **The key goes only to Seaforms over https.** One sent to another server (with `--api`) says so in the log. * **Nothing else is needed:** `pull` writes the files and their types, then your build reads them as it would on your computer. # Types for your answers > The TypeScript types the seaforms CLI writes beside each form's file. Every answer by its question's key, which thank-you showed, each step, and using them in a webhook handler. `npx seaforms pull` writes a `.seaforms.d.ts` beside each form’s file. For the contact form, `src/forms/contact.seaforms.d.ts`: src/forms/contact.seaforms.d.ts ```ts // Types for the answers to contact.seaforms.json, revision 3. // Made by the Seaforms CLI. Don't edit it: pull the form again after you publish a change. /** * A submission's answers, keyed by question, as webhooks and the Seaforms API send them. An answer * is optional when the question can be left blank or only shows sometimes. A webhook set to send * only some questions leaves the others out. */ export interface ContactAnswers { /** Name */ name: string; /** Email */ email: string; /** What’s it about? */ topic: "sales" | "support" | "press" | "something-else"; /** Message */ message: string; } /** Which thank-you showed: `ending` in `onSubmitted`. */ export type ContactEnding = "thanks"; /** The form's steps: `stepId` in `onStep`. */ export type ContactStep = "get-in-touch"; ``` Don’t edit it: pull again after you publish a change, and it’s written again. ## What’s in it * **`Answers`:** a submission’s answers, keyed by each question’s key, as [webhooks](/webhooks/events/) and the [API](/api/submissions/) send them. An answer is optional when the question can be left blank or only shows sometimes. Tick boxes, consent and quantities are always there when they always show. * **`Ending`:** which thank-you showed: `ending` in `onSubmitted` and in a submission. * **`Step`:** each step’s ID: `stepId` in `onStep`. The name comes from the form’s: `contact` gives `ContactAnswers`, `project-enquiry` gives `ProjectEnquiryAnswers`. ## Using them app/api/seaforms/route.ts ```ts import type { ContactAnswers } from "@/forms/contact.seaforms"; const answers = event.data.answers as ContactAnswers; if (answers.topic === "sales") { // … } ``` A webhook set to send only some questions leaves the others out, so treat its answers as `Partial`. ## For a file you downloaded If you saved a form’s file from the app instead of pulling it, write its types with `types`. It needs no sign-in and no network: * npm ```sh npx seaforms types src/forms ``` * pnpm ```sh pnpm dlx seaforms types src/forms ``` * yarn ```sh yarn dlx seaforms types src/forms ``` * bun ```sh bunx seaforms types src/forms ``` The types follow our logic engine itself: our tests check them against hundreds of real runs of every template, and compile them with TypeScript. # The form file > What's in a Seaforms form's .seaforms.json file. Its top-level keys, steps, blocks, questions and endings, with a real published form as the example. A published form is one JSON document, the `FormDefinition`. It’s what `npx seaforms pull` saves, what [`getForm`](/react/#getform) returns, and what `` draws. src/forms/contact.seaforms.json ```json { "schemaVersion": 1, "id": "frm_7f3kq2m4xa", "revision": 3, "locale": "en-AU", "timezone": "Australia/Adelaide", "presentation": { "mode": "steps", "progress": { "bar": false, "time": true }, "labels": { "next": "Continue", "back": "Back", "submit": "Send message" }, "estimatedSeconds": 60, "requiredMarker": "optional-label", "badge": false }, "steps": [ { "id": "get-in-touch", "title": "Get in touch", "blocks": [ { "kind": "field", "key": "name", "label": "Name", "placeholder": "Maya Chen", "required": true, "autocomplete": "name", "type": "text" }, { "kind": "field", "key": "email", "label": "Email", "placeholder": "maya@northwind.co", "required": true, "autocomplete": "email", "type": "email" }, { "kind": "field", "key": "topic", "label": "What’s it about?", "required": true, "type": "choice", "display": "chips", "options": [ { "value": "sales", "label": "Sales" }, { "value": "support", "label": "Support" }, { "value": "press", "label": "Press" }, { "value": "something-else", "label": "Something else" } ] }, { "kind": "field", "key": "message", "label": "Message", "placeholder": "How can we help?", "required": true, "type": "textarea" } ] } ], "endings": [ { "id": "thanks", "title": "Thanks, {name}.", "body": "Your message is with the right person. We usually reply the same day." } ], "features": [], "initial": { "hidden": [], "alwaysRequired": [ "name", "email", "topic", "message" ] }, "hash": "3096824560e56c78" } ``` Don't edit the file Change the form in the app, or with the [API](/api/forms/) or an [AI tool](/mcp/), and publish. Each revision has a hash, and a submission from a version Seaforms didn’t publish is kept as spam. To write a whole form, send it as a draft: `POST /v1/forms` with `from: { definition }`. ## Top-level keys * `schemaVersion`1required The format’s version. * `id`frm\_…required The form’s ID. * `revision`numberrequired The published revision. `0` in a draft. * `hash`string Set on publish: the first 16 hex characters of the SHA-256 of the form. It’s how the server knows a page runs a version it published. * `locale`stringrequired A language tag, such as `en-AU`. It sets number and date formats, and the default messages. * `timezone`stringrequired An IANA zone, such as `Australia/Adelaide`. It’s what “today” means in date rules. * `features`string\[] Set on publish: what the form uses, such as `steps`, `logic`, `files`, `payment` or `booking`. Checked against the site’s plan. * `presentation`objectrequired How it’s shown: `mode` (`steps`, `single` or `conversational`), `progress`, button `labels`, `requiredMarker` and `badge`. * `steps`Step\[]required At least one. A one-page form is one step. * `variables`Variable\[] Calculations the visitor sees or that drive logic. Pro. * `pricing`object The currency and how a total is worked out. * `endings`Ending\[]required The thank-yous. At least one, and the last has no condition. * `messages`object Your own wording for validation messages. * `assets`object Images, with their width and height so their space is kept. * `initial`object Set on publish: what shows before anyone answers, so the first render needs no script. ## Features and plans Publishing a form that uses something its site’s plan doesn’t include answers `403 plan_required`. Each value of `features` is first included on: | First on | Features | | -------- | --------------------------------------------------------------------- | | Free | `steps`, `logic`, `checks`, `priced`, `payment`, `coupons` | | Starter | `files` | | Pro | `calculations`, `summary`, `conversational`, `save-resume`, `booking` | ## Steps and blocks Step ```ts interface Step { id: string; title?: string; description?: string; blocks: Block[]; // at least one visibleWhen?: Condition; // false: the step is skipped checks?: Check[]; // rules across answers, run on Continue nextLabel?: string; } type Block = Field | Group | Content; ``` * **A field** is a [question](/format/questions/): `kind: "field"`. * **A group** is a fieldset that shows and hides as one: `kind: "group"`. * **Content** is text, an image, a divider, a price summary, a review of the answers or a discount code box: `kind: "content"`. ## Endings Ending ```ts interface Ending { id: string; when?: Condition; // the first match wins title: string; // "Thanks, {name}." body?: string; showSummary?: boolean; } ``` Text can include an answer with a token, such as `{name}`. Rich text allows `**bold**`, `*italic*`, links and paragraphs, and nothing else. ## Keys A question’s `key` is its answer’s name in webhooks, the API and your types. * It’s made from the question’s first label: “Work email” becomes `work_email`. * It can be changed until the form’s first publish, then it’s frozen, so your code keeps working when someone rewords a question. * Option `value`s work the same way: relabelling an option keeps its value. * Keys start with a letter, then lower-case letters, digits and underscores, up to 48 characters. Names like `id`, `meta`, `answers`, `files`, `payment`, `tags`, `total` and anything starting `sf_` are reserved. ## Next * [Questions](/format/questions/): every type and its properties. * [Show when and Required when](/format/logic/): the conditions. * [JSON Schema](/format/json-schema/): the exact format, for your editor or a validator. # JSON Schema > The Seaforms form format as JSON Schema. Get autocomplete and checks for .seaforms.json in your editor, validate a form in code, and read what the schema doesn't cover. The form format is published as JSON Schema (draft 2020-12), drawn from the validator every save and publish is checked with: | File | What it describes | | ---------------------------------------- | ------------------------------------------------------------------------------------- | | [`/schema/form.json`](/schema/form.json) | A form: what’s in a `.seaforms.json` file. | | [`/schema/live.json`](/schema/live.json) | A form’s [live config](/api/forms/#what-happens-after-send): what happens after Send. | ## In your editor To read a form’s file with hints and checks in VS Code or Cursor, point `*.seaforms.json` at the schema. That leaves the files themselves as they are: .vscode/settings.json ```json { "json.schemas": [ { "fileMatch": ["*.seaforms.json"], "url": "https://developer.seaforms.io/schema/form.json" } ] } ``` ## In code check-form.ts ```ts import Ajv2020 from "ajv/dist/2020.js"; const schema = await fetch("https://developer.seaforms.io/schema/form.json").then((r) => r.json()); const validate = new Ajv2020({ strict: false }).compile(schema); if (!validate(form)) console.error(validate.errors); ``` ## For AI tools The MCP connector’s [`form_schema`](/mcp/#the-tools) tool hands the same document to a connected tool, so it can write a form with exact keys and allowed values. The shape, not the whole check The schema checks a form’s shape: its keys, types and allowed values. Publishing also checks what JSON Schema can’t, such as a condition that refers to a question later in the form, a loop, or a price with no currency. Send a form as a draft (`PUT /v1/forms/{formId}/draft`), and the answer’s `issues` lists all of it. # Show when and Required when > The conditions in a Seaforms form. How visibleWhen and requiredWhen are written, every operator, how a blank answer behaves, and what a condition can refer to. Logic lives on each question and step: **Show when** (`visibleWhen`) and **Required when** (`requiredWhen`). Each holds a condition, written as JSON: A question with logic ```json { "kind": "field", "key": "company", "type": "text", "label": "Company", "visibleWhen": { "field": "contact_type", "op": "eq", "value": "business" }, "requiredWhen": { "field": "budget", "op": "in", "value": ["10k-25k", "25k-plus"] } } ``` A step with `visibleWhen` is skipped when it’s false, which is how “skip to” works. Endings use `when`, and the first that matches is the thank-you that shows. ## A condition Condition ```ts type Condition = | { all: Condition[] } | { any: Condition[] } | { not: Condition } | { field: string; op: "answered" | "empty" } | { field: string; op: BinaryOp; value: string | number | boolean | string[] | [number, number] } | { variable: string; op: NumericOp; value: number | [number, number] } | { pricing: "subtotal" | "total" | "deposit"; op: NumericOp; value: number | [number, number] }; ``` Conditions combined ```json { "all": [ { "field": "service", "op": "includes", "value": "design" }, { "any": [ { "field": "budget", "op": "gte", "value": 10000 }, { "field": "rush", "op": "eq", "value": true } ] } ] } ``` ## Operators | op | The answer… | Suits | | ------------- | -------------------------------------------- | ---------------------------------- | | `answered` | has a value | any question | | `empty` | has no value, or isn't showing | any question | | `eq` | is | text, number, one choice, tick box | | `neq` | is answered and isn't | text, number, one choice, tick box | | `in` | is one of | text, one choice | | `notIn` | is answered and isn't one of | text, one choice | | `includes` | has this one picked | several choices | | `excludes` | is answered and doesn't have this one picked | several choices | | `includesAny` | has any of these picked | several choices | | `includesAll` | has all of these picked | several choices | | `gt` | is more than | number | | `gte` | is at least | number | | `lt` | is less than | number | | `lte` | is at most | number | | `between` | is between two numbers, inclusive | number | | `before` | is before | date or time | | `after` | is after | date or time | | `on` | is on | date or time | | `contains` | contains | text | | `startsWith` | starts with | text | | `endsWith` | ends with | text | `variable` and `pricing` conditions take `eq`, `neq`, `gt`, `gte`, `lt`, `lte` and `between`. Text compares trimmed and ignoring case. Choices compare by option `value`. Dates can be relative (`today`, `+7d`), in the form’s time zone. ## A blank answer A question that’s blank, hidden or on a skipped step makes **every operator false, except `empty`**. That includes `neq`, `notIn` and `excludes`. Condition ```json { "field": "topic", "op": "neq", "value": "sales" } ``` is false while `topic` is blank. To include blank, say so with `not`: Condition ```json { "not": { "field": "topic", "op": "eq", "value": "sales" } } ``` A tick box always has a value (`false` counts), and so does a quantity (its default, or `min`). So “not ticked” is `{ "field": "invite", "op": "eq", "value": false }`. ## What a condition can refer to | Where it is | It can use | | --------------------------- | ------------------------------------------------------- | | A block’s `visibleWhen` | anything **before** that block | | A question’s `requiredWhen` | anything before it, and questions later in its own step | | A step’s `visibleWhen` | earlier steps | | A step’s `checks` | that step and earlier | | Endings | anything, including the price | Publishing refuses a form with a loop, or an operator that doesn’t suit its question. # Questions > Every question type in the Seaforms form format, the properties they share, what each answer looks like, and how choices and options work. A question is a block with `kind: "field"`: A question ```json { "kind": "field", "key": "email", "type": "email", "label": "Work email", "required": true, "placeholder": "maya@northwind.co", "autocomplete": "email" } ``` ## Every type | type | What it is | Its own properties | Its answer | | ---------- | ----------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- | | `text` | One line | `minLength`, `maxLength` (500), `pattern` | `string` | | `textarea` | Several lines | `minLength`, `maxLength` (5000), `rows` | `string` | | `email` | An email address | — | `string` | | `phone` | A phone number | `defaultCountry` | `string`, as typed | | `url` | A web address | "northwind.co" is accepted | `string`, with `https://` | | `number` | A number | `min`, `max`, `step`, `integer`, `prefix`, `suffix`, `unitPrice` | `number` | | `choice` | Pick one or several | `display`, `options`, `multiple`, `minSelected`, `maxSelected`, `other` | an option's `value`, or an array of them | | `checkbox` | One tick box | `price` (added when ticked) | `boolean` | | `consent` | Agreeing to exact wording | `body` | `boolean` | | `quantity` | A stepper | `max` (required), `min`, `step`, `unitPrice`, `unitLabel` | `integer` | | `date` | A date | `min`, `max` (a date, or `today`, `+5d`, `+3m`), `disabledWeekdays`, `blockedDates` | `"YYYY-MM-DD"` | | `time` | A time | `min`, `max`, `stepMinutes` | `"HH:mm"` | | `file` | File upload | `accept`, `maxSizeMB`, `maxFiles` (1, at most 10) | a list of files | | `rating` | Stars or a number scale | `max` (5 or 10), `display`, `min`, `minLabel`, `maxLabel` | `integer` | | `hidden` | A value the visitor doesn't see | `source`: `{ query }`, `{ const }` or `{ page }` | `string` | | `payment` | A card payment, through Stripe | `amount`: `{ fixed }`, `{ from: "total" \| "deposit" }` or `{ expr }` | the payment, set by our server | | `booking` | A date and time from the owner's calendar | `durationMinutes`, `daysAhead` (14) | the booking, set by our server | ## What every question can have * `key`stringrequired The answer’s name. Frozen at first publish. * `type`stringrequired One of the types above. * `label`stringrequired Always there, for screen readers, even when hidden with `labelHidden`. * `dataLabel`string The column name in exports and apps. Defaults to the label. * `help`rich text A line of help under the question. * `placeholder`string Shown in an empty field. * `required`boolean Must be answered. * `requiredWhen`Condition Must be answered [when this is true](/format/logic/). * `visibleWhen`Condition Only shows [when this is true](/format/logic/). * `default`answer The value it starts with. * `prefill`{ param } Fills in from the page’s address: `{ "param": "plan" }` reads `?plan=…`. Ignored on consent, file, payment, booking and hidden questions. * `autocomplete`string An HTML `autocomplete` token, such as `email` or `postal-code`. * `width`full | half | third A hint. Questions stack on a phone. * `messages`object Your own wording for this question’s errors. * `intro`string In a conversational form, a line above the question. * `personal`boolean Marks an answer as personal. Nothing reads it yet: [finding a person](/api/submissions/#find-and-erase-a-person) searches every answer. * `readOnly`boolean Shown but can’t be changed. ## Choices A choice question ```json { "kind": "field", "key": "budget", "type": "choice", "label": "What's your budget?", "display": "cards", "options": [ { "value": "under-10k", "label": "Under $10k" }, { "value": "10k-25k", "label": "$10k–$25k", "description": "Most projects" }, { "value": "25k-plus", "label": "$25k+" } ], "other": { "label": "Something else" } } ``` * `display` is `radio`, `chips`, `cards`, `segment`, `dropdown`, `swatch` or `image`. Every one is a real radio button or tick box underneath. * A question has 1 to 24 options, or up to 500 in a `dropdown`. * An option’s `value` is what answers, logic and apps use, never its label. An option can have a `price`, added when it’s picked. * With `other`, picking it sets the answer to `other`, and what the visitor typed arrives as a separate answer, `__other`. ## Files A `file` answer is a list of `{ id, name, size, type }`. In a webhook or the API each also has a `url`, and files are served from their own domain with `Content-Disposition: attachment`, so an uploaded page can never run as your site. # Your site and form IDs > Where to find a Seaforms form's ID (frm_…) and site's ID (site_…), what seaforms.json holds, and what every ID and key prefix means. Every ID in Seaforms starts with what it is, so one in a log or a file tells you what it names. IDs are case-sensitive. Use them as they are, and don’t take them apart. ## A form’s ID A form’s ID is `frm_` and ten lower-case letters and digits, such as `frm_7f3kq2m4xa`. It never changes, even when the form is renamed. You need it for [`getForm`](/react/#getform) and for the API. Find it: * **In the app:** open the form from **Forms**. Its ID is under its name, with a button to copy it. * **In its file:** the `id` at the top of `src/forms/contact.seaforms.json`. * **From the API:** `GET /v1/forms?site=site_…` lists a site’s forms with their IDs. The form’s name in the app (`contact`) is only for you and your files. It’s unique on its site, not across your workspace, so an agency can have a `contact` form on every client’s site. ## A site’s ID A site’s ID is `site_` and 26 letters and digits, such as `site_01JC8H2K4M9V6Q3T7X0B5N2R8D`. A site is one website: every form on it shares its addresses, its connected apps and its plan. You rarely type it. `npx seaforms link` (or the first `pull`) picks your project’s site and saves its ID in `seaforms.json`, at your project’s root: seaforms.json ```json { "siteId": "site_01JC8H2K4M9V6Q3T7X0B5N2R8D", "dir": "src/forms" } ``` Commit it, so everyone who pulls, and your CI, gets the same site’s forms. To choose again, run `npx seaforms link`, or give the ID yourself with `--site`. In the app, a site’s ID is under **Settings**, then **Site details**, with a button to copy it. `GET /v1/sites` lists the sites a key can see, with their IDs. ## Every prefix | Prefix | What it is | | ------- | --------------------------------------------------------------------------------------------- | | `frm_` | a form | | `site_` | a site | | `sub_` | a submission | | `blk_` | a submission caught as spam. **Not spam** turns `blk_` into `sub_`, keeping the rest. | | `ptl_` | someone who left part way | | `upl_` | an uploaded file | | `con_` | a connection: a webhook, Discord, Teams, Slack, Cal.com, Mailchimp or Stripe | | `dlv_` | one delivery of one submission to one place | | `evt_` | one webhook event | | `tpl_` | one of your workspace’s own templates | Everything after the prefix in the 26-character IDs sorts by when it was made, which is how lists page through results. ## Secrets Secrets have prefixes too, so GitHub’s secret scanning can spot one in a commit: | Prefix | Secret | Where it’s made | | -------- | --------------------------------------------------------------- | -------------------------------------------- | | `sfk_` | an [API key](/api/#api-keys) | the app, **Settings**, then **API keys** | | `sfd_` | a [dev token](/react/testing/), for trying forms on `localhost` | the app, **Settings**, then **Site details** | | `whsec_` | a [webhook’s signing secret](/webhooks/verify/) | the app, **Settings**, then **Connections** | Each is shown once, when it’s made. Keep API keys and signing secrets on your server or in your build’s environment, never in code a browser loads. # The MCP connector > Connect any AI app that supports MCP to Seaforms, such as Claude Code, Cursor, VS Code, ChatGPT or Claude. It can make, publish and place forms, choose who's emailed and read submissions if you allow it. Seaforms has an MCP server, so any AI app that supports MCP can work with your forms while you chat. It writes the form itself, from what you ask and what it knows about your site, then publishes it. A coding tool also puts its file in your code. It’s on every Seaforms plan, the free plan included. POST`https://mcp.seaforms.io/mcp` * [Claude CodeOne command, then sign in.](/mcp/claude-code/) * [ClaudeA custom connector, on every Claude plan.](/mcp/claude/) * [ChatGPTA custom MCP server, on the web.](/mcp/chatgpt/) * [![](/logos/cursor.svg)![](/logos/vscode.svg)Cursor, VS Code and othersAny app that supports MCP, or an API key.](/mcp/other/) ## What to ask it Once it’s connected, ask in your own words: * “Add a Seaforms contact form to the contact page.” * “Make a quote form from the service quote template and add a question about the budget.” * “Publish the form and put its file in the code.” * “Email me and Sam about each new enquiry.” * “Send this form’s sign-ups to our Mailchimp list.” * “Close the form after 50 entries.” ## What you approve The first time a tool connects, your browser opens Seaforms. You sign in, and it shows you: * **Who’s asking.** A tool’s name is only what it calls itself, so make sure you started connecting it yourself, just now. * **Where it sends you after you allow.** For an app on your computer, like Claude Code, this computer. For ChatGPT or Claude, their own site. Only allow if you just started connecting from there. * **The workspace and site** it works on. Choose one site to keep it to that site, or **All sites**. * **What it can do:** see your sites and forms; make, change and publish forms; and choose which of your connected apps a form sends to, open or close forms, and set the email visitors get, as far as your own role allows. * **Read what visitors sent**, off to start with. Tick it only if you want the tool to read submissions: their answers then go to the tool. You’re emailed whenever a tool connects as you, so you notice one you didn’t connect. ## The tools There are 18, and a tool only sees those its connection allows. Under each name is the access it needs: `account:read` is your workspace and sites, `forms:read` and `forms:write` your forms, and `submissions:read` is **Read what visitors sent**. ### Learn the format * `form_guide`forms:read How a Seaforms form is written: questions, steps, Show when and Required when, endings, pricing, and how the tools fit together. The tool reads it before it makes or changes a form. * `form_schema`forms:read The form format as JSON Schema, the same document as [/schema/form.json](/format/json-schema/), for exact keys and allowed values. * `list_templates`forms:read Seaforms' templates, and on Agency your workspace's own, with what each asks and whether it takes a payment, a booking or files. * `get_template`forms:read One template's whole form, so the tool can start from a working form and change it to fit. ### Sites and forms * `list_sites`account:read The sites it can work on, with each one's addresses. A site built with code shows as `npm`. * `create_site`forms:write Adds a site built with code, with the addresses its forms take submissions from. Not offered when you kept the tool to one site. * `list_forms`forms:read + account:read A site's forms: whether each is open, its published revision, and whether its draft has changes not published yet. * `create_form`forms:read + forms:write Makes a new, unpublished form: the tool's own whole form, a template as it is, or a blank one. The checker's problems come back with it. * `get_form`forms:read A form's draft and its settings: who's emailed, the apps switched on, whether it's open and the thank-you email. * `update_form`forms:read + forms:write Replaces the form's draft. Visitors see nothing until it's published. * `publish_form`forms:write Publishes the draft. If something stops it, it says what. * `get_form_code`forms:read The published form's file and its types, byte for byte what `npx seaforms pull` saves, with the lines that show it in React, Next.js or Astro. ### After Send * `set_email_alerts`forms:read + forms:write Who's emailed about each submission, picked only from you, your teammates and addresses already confirmed on the site. It never adds an address. * `list_connections`forms:read The apps the site has connected (Mailchimp, Kit, Slack, Discord, Teams, webhooks, Cal.com), whether each is on for this form, and what can be picked in each. * `set_integration`forms:read + forms:write Switches one of those apps on or off for the form. It never connects an app or enters a key: that's done in the app. * `set_form_status`forms:read + forms:write Opens, pauses or closes the form, on a date or after a number of submissions, with the message visitors see. Works at once, with no publish. * `set_thank_you_email`forms:read + forms:write The email the visitor gets after sending: on or off, its subject and message, the sender's name and where replies go. ### Submissions * `list_submissions`submissions:read The latest submissions for a site or a form, newest first, spam or not. Only when you tick **Read what visitors sent**; the answers are marked as typed by the public, never instructions. ## What it can’t do It can’t delete anything, connect a new app or enter its key (Stripe, Mailchimp or any other), add a webhook address, change your team, billing or API keys, or email an address that hasn’t confirmed. To connect an app or email someone new, do it in the app first, in **Settings**, then **Connections**, or the form’s **Integrations** tab. The tool can then use it. Connect only tools you trust A tool that can publish forms can also change where they send people, such as the page visitors go to after sending, and which of your connected apps get their submissions. Answers from submissions are what members of the public typed. Seaforms tells your tool so, along with the answers: they’re information to report, not instructions to follow. ## Signing a tool out In the app, go to **Settings**, then **Profile**. Under **AI tools**, each connected tool is listed with its site, what it does, when it connected and when it was last used. **Sign out** stops it straight away. Signing out of your browsers doesn’t sign out your AI tools. A connection also ends on its own after 90 days, or when its site is removed. When someone is removed from the workspace, every tool they connected stops too. ## Limits Each tool’s calls count toward the [API’s 300 a minute](/api/limits/), per connection. A list gives at most 50 rows, and submissions 20 unless the tool asks for more. # ChatGPT > Connect ChatGPT to Seaforms as a custom MCP server on the web, what each ChatGPT plan allows, and how to ask it for a form. Adding your own MCP server takes ChatGPT **Business, Enterprise or Edu**, on the web. On Business, an admin or owner adds it. **Pro** can connect but only read, so it can see your forms but can’t make them. 1. On [chatgpt.com](https://chatgpt.com/plugins), open **Plugins**. 2. Choose the plus button, then **Add custom MCP server**. 3. Name it `Seaforms`. Under **Connection**, paste this as the **Server URL**: Server URL ```txt https://mcp.seaforms.io/mcp ``` 4. For authentication, choose **OAuth**. 5. Read the warning, choose **I understand and want to continue**, then **Create as a plugin**. 6. Sign in to Seaforms in the window that opens. Choose your workspace and site, tick [what it can do](/mcp/#what-you-approve), and choose **Allow**. Then ask: Ask ChatGPT ```txt Make a Seaforms contact form for my site. Ask for a name, an email, what it's about and a message, publish it, and email me about each one. ``` ChatGPT makes and publishes the form with you in the chat. To put a form in a site’s code, use a coding tool such as [Claude Code](/mcp/claude-code/) or [Cursor](/mcp/other/). # Claude > Connect Claude on the web or desktop to Seaforms with a custom connector, on any Claude plan, then ask it to make and publish a form. Custom connectors are on every Claude plan. Free can add one. Claude makes and publishes the form with you in the chat. To put a form in a site’s code, use [Claude Code](/mcp/claude-code/). * Free, Pro, Max, Ultra 1. In Claude, open **Customize**, then **Connectors**. 2. Choose **+ Add**, then **Add custom connector**. 3. Name it `Seaforms`, and paste the address: Server URL ```txt https://mcp.seaforms.io/mcp ``` 4. Choose **Continue**, keep the sign-in settings as they are, and choose **Add**. 5. Connect it, and sign in to Seaforms in the window that opens. Choose your workspace and site, tick [what it can do](/mcp/#what-you-approve), and choose **Allow**. * Team, Enterprise An owner adds the connector for the organisation first. 1. In **Organization settings**, open **Connectors**. 2. Choose **Add**, hover over **Custom**, and choose **Web**. 3. Name it `Seaforms`, paste `https://mcp.seaforms.io/mcp`, and add it. 4. Each person then goes to **Customize**, then **Connectors**, finds Seaforms, chooses **Connect**, and signs in as themselves. ## Use it in a chat Choose **+** at the bottom left of the chat, then **Connectors**, and check Seaforms is on. Then ask: Ask Claude ```txt Make a Seaforms contact form for my site. Ask for a name, an email, what it's about and a message, publish it, and email me about each one. ``` # Claude Code > Connect Claude Code to Seaforms over MCP in one command, sign in, and ask it to make, publish and place a form in your site's code. 1. **Add the server.** In your project’s folder: ```sh claude mcp add --transport http seaforms https://mcp.seaforms.io/mcp ``` 2. **Sign in.** In Claude Code, type `/mcp`, choose **seaforms**, then **Authenticate**. 3. **Allow it.** Your browser opens Seaforms. Sign in with your email, choose the workspace and site, tick [what it can do](/mcp/#what-you-approve), and choose **Allow**. 4. **Ask for a form.** Ask Claude Code ```txt Add a Seaforms contact form to the contact page. Ask for a name, an email, what it's about and a message, and email me about each one. ``` Claude reads Seaforms’ guide to writing forms, makes the form, publishes it, and saves its file and types in `src/forms`. If your site isn’t in Seaforms yet, it can add it. ## For the whole team `claude mcp add` is for you, in this project. To share the server with everyone who works on the project, add it with `--scope project`, which writes a `.mcp.json` to commit. Each person still signs in as themselves. ```sh claude mcp add --transport http --scope project seaforms https://mcp.seaforms.io/mcp ``` ## Without a browser On a machine that can’t open one, use an [API key made for AI tools](/mcp/other/#with-an-api-key): ```sh claude mcp add --transport http seaforms https://mcp.seaforms.io/mcp \ --header "Authorization: Bearer $SEAFORMS_MCP_KEY" ``` # Cursor, VS Code and others > Connect Cursor, VS Code or any other app that supports MCP to Seaforms, with a browser sign-in or an API key made for AI tools. Any app that supports MCP can connect. Add this address as a remote (HTTP) server, then sign in when the app asks: POST`https://mcp.seaforms.io/mcp` * Cursor .cursor/mcp.json ```json { "mcpServers": { "seaforms": { "url": "https://mcp.seaforms.io/mcp" } } } ``` Use `~/.cursor/mcp.json` to have it in every project. Cursor then asks you to sign in. * VS Code Open the Command Palette and run **MCP: Add Server**. Choose **HTTP (HTTP or Server-Sent Events)** and enter the address. Or add it to your project: .mcp.json ```json { "mcpServers": { "seaforms": { "type": "http", "url": "https://mcp.seaforms.io/mcp", "tools": ["*"] } } } ``` Choose **Authenticate** when VS Code offers it, and sign in. * Any other app Look for **MCP**, **connectors** or **custom servers** in its settings. Add a remote server with this address, over HTTP (Streamable HTTP): Server URL ```txt https://mcp.seaforms.io/mcp ``` If it asks how to sign in, choose **OAuth**. It registers itself, so there’s no client ID to enter. Your browser opens Seaforms. Sign in, choose the workspace and site, tick [what it can do](/mcp/#what-you-approve), and choose **Allow**. ## With an API key For an app that can’t open a browser to sign in, or a job in CI. 1. In the app, go to **Settings**, then **API keys**. Only owners and admins can make one. 2. Tick **For AI tools (MCP)**. 3. Tick what it can do: **See your forms**, **Make, change and publish forms**, and **Read what visitors sent** only if it needs to. 4. Choose **Make a key**, and copy it. It’s shown once. Give it to the app as a bearer token. Keep the key in an environment variable rather than in the file: * Cursor .cursor/mcp.json ```json { "mcpServers": { "seaforms": { "url": "https://mcp.seaforms.io/mcp", "headers": { "Authorization": "Bearer ${env:SEAFORMS_MCP_KEY}" } } } } ``` * VS Code and Claude Code .mcp.json ```json { "mcpServers": { "seaforms": { "type": "http", "url": "https://mcp.seaforms.io/mcp", "headers": { "Authorization": "Bearer ${SEAFORMS_MCP_KEY}" } } } } ``` - **A key for AI tools can do only what a connected tool could**, on the [same list of tools](/mcp/#the-tools). - **Other API keys don’t work here.** - **Revoke it** in **Settings**, then **API keys**: it stops at once. Don't commit a key A config file is often committed to your project. Reference the variable, as above, and never paste the key itself. # How webhooks work > Get each Seaforms submission at your own endpoint as signed JSON. Connect a webhook, switch it on for a form, send a test, and choose which answers it gets. A webhook posts each submission to an address of yours the moment it’s stored, as JSON, signed so your code can tell it came from Seaforms. Use it to put a lead in your own system, start a job, or rebuild something. ## Connect one 1. In the app, go to **Settings**, then **Connections**, and under **Connect** choose **Webhook**. 2. Give it a **Name**, such as *My CRM*, and paste the **Address** submissions should go to. For Zapier, Make or n8n, paste the address from their webhook step. 3. If your end asks for a key, choose **Add a header** and enter it. It’s stored encrypted and never shown again. 4. Choose **Connect Webhook**. 5. Copy the **signing secret** (`whsec_…`) and keep it with your server’s secrets. It isn’t shown again. The address must be `https` on the normal port, with a hostname rather than an IP address. ## Switch it on for a form A connection belongs to the site. Each form then chooses to use it: 1. Open the form in the builder and go to the **Integrations** tab. 2. Under **Apps**, find the webhook by its name and switch it on. There’s no Save button and nothing to republish. It works from the next submission. ## Send a test In **Connections**, choose **Send a test** beside the webhook. A sample submission goes out, signed like a real one, with `"test": true`. If it doesn’t arrive, the page says why. You can send ten an hour for each connection. ## What your endpoint does 1. [Verify the signature](/webhooks/verify/) on the raw body. 2. Do the work, or queue it. We wait up to 15 seconds. 3. Answer any `2xx`. Anything else is [tried again](/webhooks/retries/). app/api/seaforms/route.ts ```ts import { Webhook } from "standardwebhooks"; import type { ContactAnswers } from "@/forms/contact.seaforms"; const webhook = new Webhook(process.env.SEAFORMS_WEBHOOK_SECRET!); type SeaformsEvent = { id: string; test: boolean; data: { submission: string; answers: ContactAnswers } }; export async function POST(request: Request) { const body = await request.text(); let event: SeaformsEvent; try { event = webhook.verify(body, Object.fromEntries(request.headers)) as SeaformsEvent; } catch { return new Response("Bad signature", { status: 400 }); } if (!event.test) await saveLead(event.data.submission, event.data.answers); return new Response(null, { status: 204 }); } ``` ## Only some of the answers A webhook gets every answer by default. To send only some, set its `options.include` to a list of question keys in the form’s [live config](/api/forms/#what-happens-after-send): Live config ```json { "id": "crm-hook", "provider": "webhook", "connectionId": "con_01JC8H2K4M7P9X3V5B8N1Q6W2T", "action": "send_webhook", "mapping": [], "options": { "include": ["name", "email", "budget"] } } ``` It limits `answers`, `labels` and `files` in the event. [The event](/webhooks/events/)Every field of the body and headers. [Verify the signature](/webhooks/verify/)With a library, or by hand in TypeScript, Python and PHP. # The event > What a Seaforms webhook posts. The headers, the submission.created body with a full example, and every field in it. Each delivery is an HTTP `POST` with a JSON body. There’s one event type today: `submission.created`. It’s sent when a submission is complete, including one that was caught as spam or marked spam and then marked **Not spam**. Each webhook gets each submission once, not counting retries. ## Headers * `webhook-id`evt\_… The event’s ID. It’s the same on every automatic retry of one delivery, and new if someone resends it by hand. * `webhook-timestamp`Unix seconds When this attempt was sent. Each retry is signed again, so one sent a day later is still fresh. * `webhook-signature`v1,\ The signature, or two separated by a space while the secret is being changed. See [Verify the signature](/webhooks/verify/). * `Content-Type`application/json Always JSON. * `User-Agent`string `Seaforms-Webhooks/1.0 (+https://developer.seaforms.io/webhooks/)` Any custom headers you set on the connection are added. ## The body POST your-endpoint ```json { "type": "submission.created", "apiVersion": "2026-11-16", "id": "evt_01JC8H2M6R5W3K9D2T4Y7B1Q8N", "createdAt": "2026-11-12T09:41:07.000Z", "test": false, "data": { "submission": "sub_01JC8H2K4M7P9X3V5B8N1Q6W2T", "form": { "id": "frm_7f3kq2m4xa", "name": "contact", "revision": 3 }, "path": [ "get-in-touch" ], "answers": { "name": "Maya Chen", "email": "maya@northwind.co", "topic": "sales", "message": "Could you quote for a new site by March?" }, "labels": { "topic": "Sales" }, "pricing": null, "tags": [], "meta": { "page": { "url": "https://northwind.co/contact", "title": "Contact · Northwind", "referrer": "https://www.google.com/" }, "timezone": "Australia/Adelaide", "locale": "en-AU", "attribution": { "utm_source": "newsletter" }, "mode": "steps", "country": "AU", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.1 Safari/605.1.15" }, "files": [], "inbox": "https://app.seaforms.io/s/sub_01JC8H2K4M7P9X3V5B8N1Q6W2T" } } ``` * `type`string `submission.created`. * `apiVersion`string The date of this payload’s format, `2026-11-16`. Fields are only ever added to it. * `id`evt\_… The event’s ID, the same as `webhook-id`. * `createdAt`RFC 3339 When the submission was stored, in UTC. * `test`boolean `true` for a test: one sent with a [dev token](/react/testing/), or by **Send a test**. * `data.submission`sub\_… The submission’s ID. Key anything your code does on this: it’s the same however many times the event arrives. * `data.form`{ id, name, revision } Which form, by its ID and its name in the app, and the published revision the visitor filled in. * `data.path`string\[] The IDs of the steps the visitor went through. * `data.answers`object The answers, keyed by each question’s key. Only what the visitor could see and answered is here. [`npx seaforms pull`](/cli/types/) writes a type for it. Each type’s value is on [Questions](/format/questions/). * `data.labels`object The display text for answers that have one: an option’s label, a formatted date or amount. Use it when you show an answer to a person. * `data.pricing`object | null The price breakdown, worked out on our server, when the form has prices. * `data.tags`string\[] Tags the form’s settings added. * `data.meta`object Where it came from: `page` (`url`, `title`, `referrer`), `timezone`, `locale`, `attribution` (UTM tags, `gclid`, `fbclid`, `msclkid`), `mode`, and `country` and `userAgent` when known. * `data.files`object\[] Uploaded files, each `{ id, field, name, size, type, url }`. `url` is an unguessable link that stays valid until the submission is deleted. * `data.inbox`string A link to this submission in the app. # Retries and repeats > How Seaforms retries a webhook that fails, when a connection is paused, and how to handle the same event arriving twice. A delivery has worked when your endpoint answers any `2xx` within **15 seconds**. Anything else is tried again. ## When it’s tried again After a failure, we wait **1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours**, each measured from the attempt before. That’s six more tries over about a day and a half. Each is signed afresh, so a late one still passes your [time check](/webhooks/verify/). * **A timeout, a connection error or any status that isn’t `2xx`** counts as a failure. * **A redirect counts as a failure too.** We don’t follow it, so a moved endpoint shows up in your log instead of quietly sending data somewhere else. * **`410 Gone`** stops the retries for that delivery, and marks the connection as failing. After the last try the delivery is marked failed, and the workspace’s owners and admins are emailed, at most once a day per form. ## See what happened In the app, open the submission in **Submissions**. **Sent to** shows whether each delivery went, with **Try again** on one that failed. The API has the same: [deliveries](/api/connections/#deliveries). ## When a connection keeps failing If every delivery to a webhook has failed for **5 days**, the connection is paused and the owners are emailed. Its submissions wait: they’re **held, not dropped**. Fix your end, then choose **Turn back on** in **Settings**, then **Connections**, and they’re all sent. ## The same event twice Retries mean an event can arrive more than once, for instance when your endpoint did the work but timed out before answering. So make your handler safe to run twice: * **`webhook-id`** is the same on every automatic retry of one delivery. Drop one you’ve seen. * **`data.submission`** is the same however the event arrived, including a manual resend, which gets a new `webhook-id`. Key anything that must happen once on it. webhook-handler.ts ```ts // Insert first: a repeat hits the unique key and does nothing. const { changes } = await db .prepare("INSERT OR IGNORE INTO leads (submission, email) VALUES (?, ?)") .bind(event.data.submission, event.data.answers.email) .run(); if (changes) await sendToSales(event.data); ``` # Verify the signature > Check that a webhook came from Seaforms. The Standard Webhooks signature, a ready-made library, and working code for Next.js, Astro, Cloudflare Workers, Node.js, Python and PHP. Anyone who learns your endpoint’s address can post to it. The signature is how your code tells a post from Seaforms from any other. Check it on every request, before you trust anything in the body. Zapier, Make and n8n don’t need this: their webhook address is the secret. ## The signature Each post carries three headers, the [Standard Webhooks](https://www.standardwebhooks.com/) way: Request headers ```http webhook-id: evt_01JC8H2M6R5W3K9D2T4Y7B1Q8N webhook-timestamp: 1763372467 webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= ``` * `webhook-id` is the event’s ID. * `webhook-timestamp` is when this attempt was sent, in Unix seconds. * `webhook-signature` is `v1,` and the base64 HMAC-SHA256 of the text `..`, where `` is the request body exactly as sent. The key is your signing secret: the part after `whsec_`, base64-decoded. While you’re [changing the secret](#changing-the-secret), the header holds two signatures separated by a space. Accept the post if either matches. ## The check 1. Read the request body as **raw text**. Don’t parse it and write it out again: a re-serialised body won’t match. 2. Refuse the post if the timestamp is more than **five minutes** from now. That stops an old post from being replayed. 3. Work out the signature with your secret. 4. Compare it to each signature in the header, in constant time. If none match, answer `400` and stop. ## With a library A Standard Webhooks library does the whole check. In JavaScript and TypeScript: * npm ```sh npm install standardwebhooks ``` * pnpm ```sh pnpm add standardwebhooks ``` * yarn ```sh yarn add standardwebhooks ``` * bun ```sh bun add standardwebhooks ``` - Next.js app/api/seaforms/route.ts ```ts import { Webhook } from "standardwebhooks"; const webhook = new Webhook(process.env.SEAFORMS_WEBHOOK_SECRET!); export async function POST(request: Request) { const body = await request.text(); let event; try { event = webhook.verify(body, Object.fromEntries(request.headers)); } catch { return new Response("Bad signature", { status: 400 }); } // event.type, event.data.answers… return new Response(null, { status: 204 }); } ``` - Astro The endpoint has to run on your server, so it needs an [adapter](https://docs.astro.build/en/guides/on-demand-rendering/) and `prerender = false`. Declare `SEAFORMS_WEBHOOK_SECRET` in `astro.config.mjs` as a server secret, as [for `getForm`](/react/astro/#add-the-form). src/pages/api/seaforms.ts ```ts import type { APIRoute } from "astro"; import { SEAFORMS_WEBHOOK_SECRET } from "astro:env/server"; import { Webhook } from "standardwebhooks"; export const prerender = false; const webhook = new Webhook(SEAFORMS_WEBHOOK_SECRET); export const POST: APIRoute = async ({ request }) => { const body = await request.text(); let event; try { event = webhook.verify(body, Object.fromEntries(request.headers)); } catch { return new Response("Bad signature", { status: 400 }); } // event.type, event.data.answers… return new Response(null, { status: 204 }); }; ``` There are Standard Webhooks libraries for [Python, PHP, Go, Ruby, Java and more](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries). ## By hand * TypeScript On Web Crypto, so it runs in Node.js, Cloudflare Workers, Deno, Bun, and Vercel and Netlify functions. verify.ts ```ts const TOLERANCE = 300; // seconds const bytes = (base64: string) => Uint8Array.from(atob(base64), (c) => c.charCodeAt(0)); export async function verifySeaforms(secret: string, body: string, headers: Headers): Promise { const id = headers.get("webhook-id"); const timestamp = headers.get("webhook-timestamp"); const signatures = headers.get("webhook-signature"); if (!id || !timestamp || !signatures || !/^\d+$/.test(timestamp)) return false; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE) return false; const key = await crypto.subtle.importKey("raw", bytes(secret.replace(/^whsec_/, "")), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]); const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`); for (const part of signatures.split(" ")) { if (!part.startsWith("v1,")) continue; try { // crypto.subtle.verify compares in constant time. if (await crypto.subtle.verify("HMAC", key, bytes(part.slice(3)), signed)) return true; } catch { // Not base64: not a signature of ours. } } return false; } ``` * Python verify.py ```python import base64 import hashlib import hmac import time TOLERANCE = 300 # seconds def verify_seaforms(secret: str, body: bytes, headers) -> bool: msg_id = headers.get("webhook-id") timestamp = headers.get("webhook-timestamp") signatures = headers.get("webhook-signature") if not msg_id or not signatures or not (timestamp or "").isdigit(): return False if abs(time.time() - int(timestamp)) > TOLERANCE: return False key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() return any( part.startswith("v1,") and hmac.compare_digest(part[3:], expected) for part in signatures.split(" ") ) ``` With Flask: app.py ```python import json import os from flask import Flask, request from verify import verify_seaforms app = Flask(__name__) @app.post("/webhooks/seaforms") def seaforms(): body = request.get_data() if not verify_seaforms(os.environ["SEAFORMS_WEBHOOK_SECRET"], body, request.headers): return "Bad signature", 400 event = json.loads(body) # event["type"], event["data"]["answers"] return "", 204 ``` * PHP webhook.php ```php TOLERANCE) { return false; } $key = base64_decode(preg_replace('/^whsec_/', '', $secret)); $expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$body", $key, true)); foreach (explode(' ', $signatures) as $part) { if (str_starts_with($part, 'v1,') && hash_equals($expected, substr($part, 3))) { return true; } } return false; } $body = file_get_contents('php://input'); if (!verify_seaforms(getenv('SEAFORMS_WEBHOOK_SECRET'), $body, $_SERVER)) { http_response_code(400); exit('Bad signature'); } $event = json_decode($body, true); // $event['type'], $event['data']['answers'] http_response_code(204); ``` ## Changing the secret In the app, go to **Settings**, then **Connections**, and choose **New signing secret** beside the webhook. Copy the new one. For the next 24 hours each post is signed with both, so you can swap the secret at your end without missing any. ## When it doesn’t verify