Widgets
Update Saved Form
Update a saved form’s name, audience, copy, theme, or content blocks
PATCH
Update Saved Form
Update an existing saved form. Every field is optional - send only what should
change. Use this to retarget the audience, edit copy, restyle the form to
match your brand, or replace the content blocks (for example to remove blocks
you no longer want rendered publicly).
A
Validation failures name the offending property, for example
Request
string
required
Saved form ID.
string
New internal form name.
string[]
Replacement list targeting. Every submission joins these lists.
string[]
Replacement tag IDs. Pass an empty array to clear tags.
string
skip, merge, or overwrite.string
New text for the form’s first heading block. Fails if the form has no heading
block - edit
blocks instead.string
New text for the form’s first paragraph block. Fails if the form has no
paragraph block - edit
blocks instead.string
New submit button label.
string
New confirmation message on the success screen.
string
HTTP or HTTPS success redirect. Pass an empty string to switch back to the
confirmation message.
object
Visual overrides merged into the current theme. Any subset of
accentColor,
backgroundColor, textColor, mutedTextColor, cardColor, borderColor
(all #rrggbb), borderRadius (0-32), headingFontFamily, bodyFontFamily,
and density (compact | balanced | spacious).object[]
Full replacement for the form’s content blocks. Read the current blocks with
GET /api/v1/forms at forms[].content.blocks, modify them, and send the
complete array. The form must keep exactly one required email field and one
submit button. See Content blocks below.Content blocks
Blocks render in array order. Every block needs anid that is unique across
the entire block tree and a kind.
Content blocks (heading, text, image, button, divider, spacer,
custom-html, feature-grid, testimonial, countdown) may also set
sectionId to "success" or "error" to render inside that screen; input
blocks, the submit button, and the success and error blocks always belong to
the form itself.
Available kinds: group, form-field, form-step, submit-button,
success-screen, error-state, plus the content kinds above.
Properties outside a kind’s list are rejected with a named error rather than
dropped, so a typo is reported instead of saving an empty block.
Content block properties
Rich-text limits apply to visible text after stripping HTML and trimming:
heading
content 1-180 characters, text content up to 700, feature title
up to 120 and description up to 300, testimonial quote 1-500, and
success-screen heading up to 120 and message 1-240. Inline HTML is
sanitized. The raw markup may use up to five times the visible-text limit
plus 500 characters. A feature must have visible text in its title or description.
Layout groups
Usekind: "group" to keep related sibling blocks together and control their
responsive layout. stack uses one column, row gives every child an equal
column, and grid uses columns. Responsive rows and grids collapse to one
column on small screens. overlay uses exactly one direct image child as the
background and places the remaining children above it. Use overlayColor,
overlayShade (0-100), and overlayPosition (top, center, or bottom) to
control its treatment. gap spaces the foreground children without moving the
background image. Images inside subgroups only enable Overlay for that subgroup;
zero or multiple direct images fall back to Stack.
Groups may nest up to three levels. A group and all descendants must belong to
the same form state: either omit sectionId throughout for the main form, or
set the same "success" or "error" value on the group and every descendant.
form-step, success-screen, and error-state blocks must remain at the root.
custom-html block carries its markup in html - not content - and sizes
its frame with height in pixels:
Form field blocks
kind: "form-field" renders one input. Fields that are not mapped to a
built-in subscriber property are stored as subscriber custom attributes keyed
by the block’s name.
string
default:"text"
text, email, phone, number, textarea, select, radio, checkbox,
consent, or hidden.string
required
The submitted key, and the custom attribute key when
mapsTo is
customAttribute. Must start with a letter and may contain letters, digits,
_, ., and -. Field names must be unique within a form.string
default:"customAttribute"
email, firstName, lastName, phone, or customAttribute. The email
field must use fieldType: "email" and required: true; first and last name
fields must use fieldType: "text"; a mapped phone field must use fieldType: "phone". A form may contain at most one field per built-in target.string
Accessible name, also shown above the input unless
showLabel is false.string
Placeholder text. Also used as the empty option’s label on
select.boolean
default:"false"
Whether submissions without a value are rejected.
string
Pre-filled value. On a
hidden field this is the server-owned value (see
below).boolean
default:"true"
Whether the label renders above the input.
string
full or half. Adjacent half fields pair side by side and stack on
mobile.object[]
Required for
select, radio, and checkbox: [{ "value": "pro", "label": "Pro", "id": "pro" }]. Only value is required - label and id default
to value. Values and ids must be unique within the field, and submissions
outside the option values are rejected. A checkbox field stores an array of
the selected values.Hidden fields
Ahidden field with a non-empty defaultValue always stores that
server-owned value and ignores whatever the page posts, which is how you stamp
a constant such as a form source. A hidden field with an empty
defaultValue stores the value the page submits, which is how you pass
machine-filled data such as UTM parameters or a page URL. A required hidden
field must have a defaultValue.
Example
blocks[1].options[0].value: Too small: expected string to have >=1 characters.