Create a form
Makes a draft from `document`, from a `starter`, or from a one-field email form when you send neither, and returns the whole form. Send `publish: true` to put it live in the same call.
Runs the real call on your workspace.
POST /forms
Makes a draft from document, from a starter, or from a one-field email form when you send neither, and returns the whole form. Send publish: true to put it live in the same call.
Example
Needs forms:write, and emails:send as well when it turns on double opt-in, names a sender or sets the confirmation email.
curl -X POST "$OE/forms" -H "$AUTH" -H 'content-type: application/json' -d '{ "name": "Newsletter sign-up", "starter": "newsletter", "settings": { "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"], "doubleOptIn": true, "senderAddress": "[email protected]" }, "publish": true}'{ "object": "form", "id": "frm_3b9d2e7a1c4f80d56e2a9b14", "name": "Newsletter sign-up", "description": null, "status": "live", "url": "https://openemail.uk/form/frm_3b9d2e7a1c4f80d56e2a9b14", "subscribeUrl": "https://api.openemail.uk/subscribe/frm_3b9d2e7a1c4f80d56e2a9b14", "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"], "doubleOptIn": true, "hasUnpublishedChanges": true, "document": { "fields": [ { "id": "fld_k2m8q4w9z1x7", "type": "email", "key": "email", "label": "Email", "placeholder": "[email protected]", "help": null, "required": true, "defaultValue": null, "options": [], "mapsTo": "email", "width": "full", "minLength": null, "maxLength": null, "min": null, "max": null } ], "copy": { "title": "Join our list", "description": "News from us, about once a month.", "submitLabel": "Subscribe", "successTitle": "You are on the list", "successMessage": "Thanks for signing up.", "pendingTitle": "Check your inbox", "pendingMessage": "Open the email we sent and confirm to finish.", "closedTitle": "This form is closed", "closedMessage": "It is not taking new sign-ups right now.", "footer": null }, "style": { "accent": "#18181b", "background": "#f4f4f5", "surface": "#ffffff", "text": "#18181b", "font": "system", "radius": "md", "width": "normal", "layout": "card", "align": "left", "logoUrl": null } }, "publishedDocument": { "fields": ["…"], "copy": { "title": "Join the list" }, "style": { "accent": "#18181b" } }, "settings": { "audienceIds": ["aud_4c1b8e2a7d9f05c36b4e8a71"], "doubleOptIn": true, "senderAddress": "[email protected]", "confirmSubject": "Please confirm your subscription", "confirmMessage": "Confirm your email address to start getting our messages.", "confirmButton": "Confirm my subscription", "successAction": "message", "redirectUrl": null, "notifyAddresses": ["[email protected]"] }, "audiences": [{ "id": "aud_4c1b8e2a7d9f05c36b4e8a71", "name": "Newsletter", "builtin": false }], "senderIssue": null, "senderProblem": null, "stats": { "views": 1840, "submissions": 212, "added": 198, "pending": 14, "lastSubmittedAt": "2026-09-30T16:42:11.000Z" }, "publishedAt": "2026-09-12T08:00:00.000Z", "createdAt": "2026-09-10T14:20:00.000Z", "updatedAt": "2026-09-12T08:00:00.000Z"}settings takes any subset of the settings, and the rest keep their defaults.
Every audience in settings.audienceIds, and in an audiences field, has to be an audience you can reach in this workspace, or the answer is 404 audience_not_found.
A double opt-in form needs settings.senderAddress, an address you may send as. A sender that cannot send is refused with 422 form_sender_refused.
When publish is true and the form cannot be published, nothing is created.
A workspace holds 100 forms by default. The next one is refused with 422 workspace_limit_reached.
