Every form key

A form lives in site/schema/forms/<handle>.yml. This page lists every key it takes, one row each, with nested keys written as a path (spam.rate_limit.requests is requests under rate_limit under spam). bin/rails nibble:check refuses a form with a key not listed here, a key of the wrong type or a value it can’t use.

“Text” in the Type column means a string, or a map of locale to string on a site with several locales.

1. The form

Key	Type	Default	Meaning	Explained in
title	text	required	the form’s name, shown to visitors and in emails	Forms
fields	list		the form’s fields, in order; give fields or sections, not both	Forms
sections	list		groups of fields; each is { display, instructions, fields }	Forms
steps	true / false	false	each section becomes a step; needs sections	Steps
submit_label	text	the theme’s “Send message”	the send button’s text	Translating
success	map		what the visitor sees after sending	Forms
success.message	text		shown in place of the form; may use {global.<set>.<field>}	Forms
success.redirect	text		an on-site path or an http(s) address to send the visitor to	Forms
store	true / false	true	keep submissions; false keeps nothing, and emails and deliveries still happen	Retention
retention_days	whole number	kept until deleted	delete submissions older than this many days	Retention
cp_notify	true / false	false	notify Control Plane users who can see the form’s submissions	Delivery
handler	text		the name of a registered Ruby handler	Handlers

2. Finishing later

Key	Type	Default	Meaning	Explained in
resume	true / false	false	adds Save and finish later; needs store on	Steps
resume_email	text		the handle of the text field that holds the visitor’s address	Steps
resume_days	whole number	7	how many days the link works	Steps

3. Emailing: notify

notify is a list; each entry sends one email per submission.

Key	Type	Default	Meaning	Explained in
notify.to	address or list	required	who gets it: an address, {field.<handle>} or {global.<set>.<field>}	Delivery
notify.cc, notify.bcc	address or list		copies, written like to	Delivery
notify.subject	text	“New submission: title”	the subject; merges {field.x}, {form.title} and {global.set.field}	Delivery
notify.message	text		text shown above the fields; merges like subject	Delivery
notify.reply_to	field handle		the field whose address Reply answers	Delivery
notify.fields	list of field handles	every field	what the email includes	Delivery
notify.if, notify.if_any, notify.unless, notify.unless_any, notify.show_when, notify.show_when_any, notify.hide_when, notify.hide_when_any	map of field handle to value		send the entry only when the submission matches	Delivery

4. Other systems: api

api is a list; each entry is one delivery.

Key	Type	Default	Meaning	Explained in
api.url	text		an absolute http(s) address; give url or use	Delivery
api.use	text		the handle of an API connection	Connections
api.path	text		with use, the path under the connection’s base_url	Connections
api.method	post, put, patch	post	the HTTP method	A delivery
api.format	json, form	json	how the body is encoded	A delivery
api.body	map	the whole submission	what to send; values merge {field.x}, {secret.x}, {config.x}	A delivery
api.mode	async, sync	async	sync makes the visitor wait and shows a rejection on the form	Delivery
api.errors	map		how to read a rejection	Delivery
api.errors.status	list of numbers	[400, 422]	the answers that count as rejected, not failed	Delivery
api.errors.path	dotted keys	errors	where the field errors are in the JSON answer	Delivery
api.errors.field, api.errors.message	text	field, message	the two keys of an error written as { field, message }	Delivery
api.error_fields	map		renames the other system’s field names to the form’s	Delivery
api.retry	map		how a failed delivery is retried	A delivery
api.retry.attempts	whole number	3	tries in all	A delivery
api.retry.backoff_seconds	whole number	30	the wait before the second try; it doubles each time	A delivery

An API connection is its own file in site/schema/apis/<handle>.yml:

Key	Type	Default	Meaning	Explained in
base_url	text	required	the address paths are added to; may use {config.x} and {secret.x}	Connections
headers	map		sent with every request; may use {secret.x}	Connections
timeout	whole number	10	seconds a request waits	Connections
errors	map		the same as api.errors; a delivery’s own keys win	Connections
retry	map	3 attempts, 30 seconds	the same as api.retry; a delivery’s own keys win	A delivery

5. Spam: spam

Key	Type	Default	Meaning	Explained in
spam.honeypot	text or false	_nibble_hp	the hidden field’s name; false turns it off	Spam
spam.rate_limit	map		accepted submissions per address	Spam
spam.rate_limit.requests	whole number	5	submissions allowed in the window	Spam
spam.rate_limit.per_minutes	whole number	1	the window, in minutes	Spam
spam.captcha	true / false	false	require a CAPTCHA; keys are set under Site settings → Integrations	Spam
spam.min_seconds	whole number	off	a submission sent sooner than this after the form was shown is spam	Spam
spam.max_links	whole number	off	more links than this in the text fields is spam; 0 allows none	Spam
spam.retention_days	whole number	30	delete spam after this many days	Spam

6. Limits: limits

Key	Type	Default	Meaning	Explained in
limits.opens_at	quoted date and time	open	the form refuses submissions before this	Limits
limits.closes_at	quoted date and time	never	the form refuses submissions from this	Limits
limits.max_submissions	whole number	no cap	the form closes once this many are stored; spam doesn’t count	Limits
limits.unique	list of field handles		fields whose value is accepted once	Limits
limits.closed_message	text	“This form isn’t taking submissions right now.”	shown when the form is closed	Limits

7. Keys on a form’s fields

A form’s fields are declared as in a blueprint, and these options matter on a form.

Key	Explained in
a field’s encrypt — true stores its value encrypted; not on files, nor with store: false	Encrypting
a field’s hidden, value and prefill — a field the visitor never sees, with a fixed or query-string value	Forms
a field’s messages — the text shown when one of its rules fails, per locale	Forms
a text field’s input_type — email, url and tel check the value	Text that is checked
a toggle field’s inline_label — text beside the box, which may hold Markdown links	A consent checkbox
a note field’s text — Markdown shown between fields; stores nothing	Notes
a calculation field’s formula, decimals, prepend, append — the formula (required), places to round to (0–15), and text around the figure	Calculations
a decimal field’s decimals, min, max, step, placeholder, prepend, append — places kept (0–10, default 2), bounds, the input’s step, and text in and around the input	Forms
a range field’s min, max, step, default, prepend, append — the scale (0, 100 and 1 by default), where it starts, and text around the value	Forms
a rating field’s max — the number of stars, 2–10 (default 5)	Forms
a files field’s max_files, max_file_size and extensions — limit uploads	Forms