Settings, properties, access, and styles

Besides its pages, a Form Blueprint carries four form-level blocks. You write settings, properties, and the theme in styles; access is read-only on a draft write and owned by the access operations. All four are optional on write and always present on read. Their booleans are integer booleans: they read as 1, 0, or null.

On a draft write, a key you leave out keeps its stored value, so you can send only the fields you change. On create, a key you leave out receives the default listed below. To reset a field on an existing form, send its default.

Settings

Every field is listed in the request body of Replace the draft document, under settings.

• email_notifications_enabled_owner sends an email to the owner recipients for each submission. Default 0.
• email_notifications_recipients_owner lists who receives that email: the addresses of active members of the organization, at most ten. Default []. When you turn owner emails on and the list is empty, the token owner is added, as the app adds you when you switch the setting on. An address that is not an active member is 400 INVALID_INPUT at its index. Send an empty list to stop sending to anyone without turning the setting off.
• email_notifications_enabled_respondent sends respondents a confirmation email. Default 0.
• email_notifications_recipient_respondent is the public ID of the Email block (text_input_email) whose answer receives the confirmation, or null. Default null. Any other block is 400 INVALID_INPUT. Respondent emails are not sent until it names an Email block, as the app warns.

Subjects and email templates are not part of the document; they are edited in the app, as described in Notifications. A write that changes the recipients keeps the stored subject and template untouched. Draft writes that change respondent email settings on a live form go through the same automated safety checks as the app, and an abusive change is refused with 422 FORM_SAFETY_REJECTED.

Pro feature

Respondent confirmation emails are a Fomr Pro feature (respondent_email_notifications). A Free organization that sets email_notifications_enabled_respondent to 1, or sets email_notifications_recipient_respondent, gets 402 PRO_FEATURE_REQUIRED.

Properties

Every field is listed in the request body of Replace the draft document, under properties.

• show_branding controls the “Made with Fomr” branding. See Hide branding.
• auto_jump_next_page is the form-wide switch for automatic page advancing. Default 1. Each page’s read-only is_auto_jump_next_page shows whether that page qualifies, as described in Pages.
• allow_back_navigation lets respondents return to earlier pages, with the Back button or by clicking a visited step of the progress bar. Default 1. See Page navigation.
• meta_title, meta_description, meta_index, meta_favicon_url, and meta_ogimage_url shape link previews and search results. All default to null, except meta_index, which defaults to 0. The favicon and preview image must be https URLs, as in the app; a new http URL is 400 INVALID_INPUT, while a stored one keeps round-tripping. See Link preview and SEO.
• partial_response_capture_enabled captures answers before the form is submitted. Default 1. See Partial responses.

Pro features

Some property values need Fomr Pro. On a Free organization:

Field	Feature	Free organizations
show_branding	hide_branding	Always 1. A write that sends 0 succeeds and the value is ignored.
meta_title, meta_description	meta_tags	Any non-null value gets 402 PRO_FEATURE_REQUIRED.
meta_index, meta_favicon_url, meta_ogimage_url	meta_tags	Any value other than 0, null, or empty gets 402 PRO_FEATURE_REQUIRED.
partial_response_capture_enabled	partial_response_access	Sending 0 gets 402 PRO_FEATURE_REQUIRED: capture stays on.

On a Pro organization, a form created without show_branding gets 0, which hides the branding, as a form created in the app does. A draft write that leaves it out keeps the stored value.

A value already stored, for example from a time the organization was on Pro, is not refused when a write keeps it unchanged, whether you send it again or leave the key out. Only a change to a Pro value is refused. Search-engine properties still block publishing on Free, as listed in Publish Validation.

Access

Every field is listed in the response of Read the draft document, under access.

The access block shows whether the form accepts submissions. It is read-only in a draft write, where the close, reopen, and access operations own it; it is honored when you create a form. is_closed is an integer boolean; close_at and open_at are ISO 8601 timestamps or null. Form access & scheduling describes what closing and scheduling mean for respondents.

duplicate_response_rule blocks a second completed response, as Prevent duplicate responses describes. It is null when every response is accepted, or one of:

Rule	Blocks a response that
{ "type": "ip_address" }	comes from an IP address that already completed the form
{ "type": "submission_id" }	comes from a browser that already completed the form
{ "type": "component", "node_public_id": "nEml" }	repeats an earlier answer to that question

A component rule must name a visible text_input_short, text_input_email, phone_number_input, text_input_link, or number_input block on a visible page, the questions the app offers. Any other block is 400 INVALID_INPUT at duplicate_response_rule/node_public_id.

Styles

Every field is listed in the response of Read the draft document, under styles.

The styles block describes the theme applied to the form. theme_id is writable on create and on a draft write: send the ID of a system theme or a theme of your organization from GET /v1/themes. Left out on create, the form gets the default theme; left out on a draft write, the current theme is kept; null applies the default theme. An unknown ID is 400 INVALID_INPUT at styles/theme_id. Changing the theme clears the form’s color, font, border, and option layout overrides, as the app does; see Applying a theme.

theme_name names the applied theme and override_properties lists the form’s overrides of the theme, or is null when it has none. Both are read-only; overrides are edited in the app, as described in Design & themes.

Theme override

Every field is listed in the request body of Replace the draft document, under styles › theme_override.

Each field overrides one theme property, and null means the theme value applies. The palettes, primary_color and option_colors, are JSON-encoded strings: a string holding an array of hex values, not a JSON array.