Forms
A form is a content model of kind form: a set of fields your site renders and visitors fill in. Each time a visitor submits it, Plenary validates the values against the form’s fields, screens them for spam, and stores a form entry, a read-only record that editors triage in the console. Use forms for contact, signup, and application pages, anywhere visitors send data to you rather than editors publishing data to them.
Plenary does not render forms for you. Your site reads the form’s definition with getForm from @plenary/client, builds its own markup, and submits with submitForm. The contact form example is a complete Next.js build; the Forms API reference has every endpoint and error code.
How forms differ from content models
Section titled “How forms differ from content models”Forms share the field system with content models, but a form entry is a record, not content:
| Content model | Form | |
|---|---|---|
| Records are called | entries | form entries |
| Written by | editors, and API keys with grants | anyone holding a public API key for the form’s site |
| Lifecycle | draft → published |
triage status: new, read, archived, spam |
| Editable after save | yes | no; only the status changes |
| Revision history | yes | no |
| Localized fields, slugs, folders, scheduling | yes | no |
| API surface | /api/v1/models, /api/v1/content |
/api/v1/forms |
A form also cannot be marked private (a public key could no longer submit it), cannot have a plural name, title field, or preview, and does not run transformers. The API rejects these settings on a form rather than ignoring them.
Field types a form can use
Section titled “Field types a form can use”| Allowed | Not allowed |
|---|---|
text, number, boolean, date, time, datetime, email, url, phone, color, select, multi_select, tags, object, list, json |
image, file, rich_text, reference, computed, blocks |
The excluded types each need something a public form cannot safely offer:
imageandfilewould need an unauthenticated upload path into your media library. If you need attachments, upload them to storage you control and submit the resulting URL in aurlfield.rich_textwould store visitor-supplied HTML, which needs an inbound sanitizer first.referenceandcomputedhold data a visitor does not author.blocksis a page-builder tree and has no meaning in a form.
The server enforces this list when a form is created and on every update (422 model_form_field_type_not_allowed). See Field types for each type’s value shape.
Create a form in the console
Section titled “Create a form in the console”- Go to Forms and click New form.
- On the Settings tab, under Details, fill in Name and Key. The key is the lowercase identifier your site passes to
getForm("contact")and the one in the submit URL. The form belongs to the site selected in the console’s site switcher and accepts entries on that site only. - On the Fields tab, click Add field for each input. Mark fields required, and set UI hints (placeholder, help text, a
textareacontrol for long text) and validation rules (for examplemin_lengthandmax_lengthon text). Your renderer receives all of these in the definition. - Click Save form.
A new form is Active. There is no publish step: an active form is readable by public API keys and accepts entries immediately. To stop accepting entries, open the form’s Settings tab and, under Status & deletion, set the status to Inactive. An inactive form answers both the definition read and submits with 404 form_not_found; its existing form entries are kept.
You can also create forms with POST /api/v1/forms (see the Forms API reference) or keep them in version control as YAML (see Models as code).
Render and submit a form
Section titled “Render and submit a form”Your site needs a public API key that belongs to the same site as the form. Create one under Access Management → API Keys (see API keys). A public key holds no permissions, but it may read an active form’s definition and submit entries to it.
import { createClient } from "@plenary/client";
export const plenary = createClient({ baseUrl: process.env.PLENARY_BASE_URL ?? "", // e.g. https://your-instance.plenarycms.io apiKey: process.env.PLENARY_API_KEY ?? "", siteKey: process.env.PLENARY_SITE_KEY ?? "", locale: "en-us",});Read the definition, render one input per field, then submit the values keyed by field key:
import { plenary } from "./lib/plenary";
const form = await plenary.getForm("contact");// form.fields: [{ key, name, type, required, settings?, ui?, validation? }]// form.ts: the anti-spam token; send it back unchanged on submit
const result = await plenary.submitForm( "contact", { name: "Jane Doe", email: "jane@example.com", message: "Hello there." }, { website: "", ts: form.ts },);// result: { ok: true, id: "5659896a-9736-4834-9a1c-b460cdee2349" }Rendering from the definition rather than hand-writing the markup keeps the two in step. When someone adds a required field in the console, your form shows it, instead of the server rejecting entries for a field the visitor never saw.
Values use native JSON types: strings for text-like fields and select, numbers for number, booleans for boolean, arrays of strings for multi_select and tags, objects for object and json, and arrays for list. An empty string or null for an email, url, phone, select, number, date, time, datetime, or color field means “not answered”.
Spam protection
Section titled “Spam protection”Every form has two spam checks. They are always on and have nothing to configure. Neither one rejects a submission: a caught entry is stored with status spam and the visitor gets the same 202 response as everyone else, so a bot learns nothing and a misfiled human can be recovered from the spam view. Spam entries never send email notifications or trigger webhooks.
Your form sends two extra keys as top-level siblings of data, never inside it:
| Key | What to send | Classified as spam when |
|---|---|---|
website |
The value of a text input named website that you hide off-screen. Humans leave it empty. |
It is non-empty. |
ts |
The ts string from the form definition, unchanged. |
It arrives less than 3 seconds after the definition was read, or its signature does not verify. |
{ "data": { "name": "Jane Doe", "email": "jane@example.com", "message": "Hello there." }, "website": "", "ts": "MTc5MTM2NDM2Ni5KTjE0RTNQQzVlQlZybDBNRGgtZDYzTlMwWWtyRVpmY2hMU3Y0elNTT3pV"}With submitForm, pass them as options: submitForm(formKey, data, { website, ts }).
Hide the honeypot with off-screen positioning (for example position: absolute; left: -10000px), not display: none alone. Give the input tabIndex={-1} and autoComplete="off", and put aria-hidden="true" on its wrapper so keyboard and screen-reader users never reach it.
Both keys are optional. If you never send website, nothing is checked. If you never send ts, no time check runs, so a hand-written integration that never reads the definition still works.
Separately, submissions are rate-limited to 10 per minute per form per client IP (429 form_entry_rate_limited). This is an abuse ceiling, not a spam filter. It is off on instances running with dev_mode: true.
Validation and per-field errors
Section titled “Validation and per-field errors”A submission is validated with the same code that validates content entries. When a value fails, the response is 422 with an error code and the offending field in vars.field:
{ "error": { "code": "entry_field_rule_violation", "vars": { "field": "message", "name": "Message", "rule": "min_length", "min_length": 10 } }}The server stops at the first failing field, so each response names one field. To show every problem at once, validate in the browser too: the definition includes each field’s required flag and validation rules, which map onto HTML attributes such as required, minlength, and maxlength. @plenary/client throws a PlenaryValidationError carrying code and vars. See Submit errors for every code.
The server checks that each field is known, that required fields are present and non-empty, that each value has the right JSON type, that phone values are E.164 (+15555550123) and color values are hex, and the min_length, max_length, and regex rules on text fields.
Email notifications
Section titled “Email notifications”A form can email users when it receives a new entry. Open the form’s Settings tab and use the Email Notifications card:
- Turn on Send email notifications.
- Add recipients with Add recipient(s): individual users, or a role. A role means every active user of that role who has an email address at the time of sending, so someone added to the role later receives later notifications.
- Include form data in email is off by default. Off, the email names the form, site, and time, and links to the entry in the console, which keeps visitor data out of inboxes. On, it also lists every submitted value.
Notifications need an email provider configured under Admin Settings (see Settings); the card warns you when none is set. Sending is queued and retried in the background, so the visitor’s response never waits on the mail provider. Spam entries never notify. The email bodies are the form-notification and form-notification-data message templates, which you can edit like any other template.
Configuring notifications requires content:forms:update on the form. The same settings are available through the API; see Email notifications in the reference.
Triage, export, and delete form entries
Section titled “Triage, export, and delete form entries”Go to Forms and click Open entries on a form’s card. The table lists form entries newest first, with the form’s fields as columns.
- Status. Every entry starts as New, or Spam if a check caught it. Select rows and use Mark as to move them to Read, Archived, Spam, or back to New. Opening an entry shows its submitted values and its Provenance: submission time, site, IP address, user agent, and referer.
- Export. Export CSV downloads the rows currently on screen, with the columns currently shown, as a UTF-8 CSV. That is the current page (25 rows) with its filters applied, not the whole form. To export everything, page through
GET /api/v1/forms/{form_key}/entrieswithlimit(up to 500) andoffset. - Delete. Select rows and choose Delete…. Deletion is permanent.
Submitted values cannot be edited; a form entry is a record of what the visitor sent.
Permissions
Section titled “Permissions”Form capabilities are separate from content capabilities, so you can give someone triage access without letting them edit forms or content.
| Capability | Allows |
|---|---|
content:forms:read |
See forms and their definitions in the console |
content:forms:create |
Create forms |
content:forms:update |
Edit fields and settings, and configure email notifications |
content:forms:delete |
Delete forms |
content:form_entries:read |
List and open form entries (also lists the forms, so a triager can reach them) |
content:form_entries:update |
Change a form entry’s status |
content:form_entries:delete |
Delete form entries |
content:webhooks:manage |
Configure webhooks on a form |
Each can be scoped to a single form, and the content:form_entries:* capabilities can also be scoped to a site. The built-in Editor role holds content:forms:read and all three content:form_entries:* capabilities; Developer holds every form capability. Submitting a form needs none of them. See Permissions.
Send form entries to other systems
Section titled “Send form entries to other systems”To push each new entry to a CRM, a chat channel, or a spam filter, add a webhook on the form’s Webhooks tab. A form webhook subscribes to one event, form.submitted, and receives the stored values plus the entry’s source block. Spam entries do not fire it. A site webhook on the form’s site can subscribe to form.submitted too. See Webhooks and the form.submitted payload.
Delete a form
Section titled “Delete a form”On the form’s Settings tab, Delete form removes the form after you type its key to confirm. If the form still has entries, deletion is refused unless you also tick Also delete all form entries. Through the API, DELETE /api/v1/forms/{form_id}?key_confirm={form_key} does the same, with &purge_content=1 to delete the entries.
Related
Section titled “Related”- Contact form example: a complete Next.js App Router build
- Forms API reference
- Webhook events
@plenary/client