PUT
/v1/forms/{form_public_id}/draft
const url = 'https://platform.fomr.io/v1/forms/example/draft?dry_run=true';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","hidden_values":[],"logic_rules":[{"public_id":"example","conditions":{"match":"all","items":[{"kind":"condition","id":"example","subject":{"type":"answer","node_public_id":"example"},"operator":"is","value":["example"]}]},"actions":[{"id":"example","type":"show","target":{"kind":"node","node_public_id":"example"}}]}],"calculated_values":[{"public_id":"example","name":"example","type":"number","initial_value":"example"}],"pages":[{"public_id":"example","name":"example","type":"intro","is_hidden":false,"is_entrypoint":true,"nodes":[{"public_id":"example","parent_node_id":"example","column_index":1,"sort_order":1,"is_hidden":false,"type":"actions","meta":{"label":"example","is_page_actions_override":false,"show_back_button":true,"back_button_label":"Back","show_button_arrows":true,"action_button_alignment":"left"}}]}],"settings":{"email_notifications_enabled_owner":0,"email_notifications_enabled_respondent":0,"email_notifications_recipients_owner":["[email protected]"],"email_notifications_recipient_respondent":"example"},"properties":{"show_branding":0,"auto_jump_next_page":0,"allow_back_navigation":0,"meta_title":"example","meta_description":"example","meta_index":0,"meta_favicon_url":"https://example.com","meta_ogimage_url":"https://example.com","partial_response_capture_enabled":0},"styles":{"theme_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url 'https://platform.fomr.io/v1/forms/example/draft?dry_run=true' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "hidden_values": [], "logic_rules": [ { "public_id": "example", "conditions": { "match": "all", "items": [ { "kind": "condition", "id": "example", "subject": { "type": "answer", "node_public_id": "example" }, "operator": "is", "value": [ "example" ] } ] }, "actions": [ { "id": "example", "type": "show", "target": { "kind": "node", "node_public_id": "example" } } ] } ], "calculated_values": [ { "public_id": "example", "name": "example", "type": "number", "initial_value": "example" } ], "pages": [ { "public_id": "example", "name": "example", "type": "intro", "is_hidden": false, "is_entrypoint": true, "nodes": [ { "public_id": "example", "parent_node_id": "example", "column_index": 1, "sort_order": 1, "is_hidden": false, "type": "actions", "meta": { "label": "example", "is_page_actions_override": false, "show_back_button": true, "back_button_label": "Back", "show_button_arrows": true, "action_button_alignment": "left" } } ] } ], "settings": { "email_notifications_enabled_owner": 0, "email_notifications_enabled_respondent": 0, "email_notifications_recipients_owner": [ "[email protected]" ], "email_notifications_recipient_respondent": "example" }, "properties": { "show_branding": 0, "auto_jump_next_page": 0, "allow_back_navigation": 0, "meta_title": "example", "meta_description": "example", "meta_index": 0, "meta_favicon_url": "https://example.com", "meta_ogimage_url": "https://example.com", "partial_response_capture_enabled": 0 }, "styles": { "theme_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" } }'Replaces the Draft Document with the one you send. Pages and blocks are matched by public ID and updated in place, so database IDs, answers, and pipe references survive; an item without an ID is created with a server-minted ID; an item you leave out is removed and its answers are kept; a removed ID you send again is restored. Page order is the array order and the first page is the entrypoint. is_template and access are read-only here and ignored; styles.theme_id changes the theme, and the other styles fields are read-only. A document identical to the stored one writes nothing and returns the same ETag. Use dry_run=true to validate without writing. Needs forms:write, or templates:write for a Private Template. Costs 1 API credit.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”form_public_id
required
string
The public ID of the form or Private Template.
Query Parameters
Section titled “Query Parameters”dry_run
string
Validate the document and resolve every ID without writing anything. Costs the same as a real write and answers 200 with the document the real call would have stored, without an ETag.
Request Body
Section titled “Request Body”Media typeapplication/json
object
public_id
Public ID of the form (10 characters). Read-only: assigned by the server on create and ignored on write.
string
name
required
Form name shown in the app.
string
is_template
Whether the resource is a Private Template. Read-only on draft writes; honored when creating a form.
boolean
hidden_values
logic_rules
Conditional logic rules in evaluation order. Rules show, hide, require, or skip to pages, update Calculated values, and redirect (Pro) based on answers, Hidden values, and Calculated values. Rule, condition, and action IDs are 1-22 URL-safe characters chosen by the client and must stay stable. Left out on a draft write, the stored list is kept; send an empty list to remove every entry.
Array<object>
object
public_id
required
Public ID of the rule, unique within the form. 1-22 URL-safe characters.
string
conditions
required
When the rule applies.
object
match
required
Whether all or any of the items must match. A rule without items always applies.
string
items
required
Conditions and condition groups.
Array
One of:
object
kind
required
Marks a single condition.
string
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
subject
required
One of:
object
type
required
What the condition tests.
string
node_public_id
required
Public ID of the question whose answer is tested.
string
object
type
required
What the condition tests.
string
key
required
Key of the Hidden value that is tested.
string
object
type
required
What the condition tests.
string
calculated_value_public_id
required
Public ID of the Calculated value that is tested.
string
object
type
required
What the condition tests.
string
page_public_id
required
Public ID of the page the respondent must have visited.
string
object
type
required
Matches once the respondent reaches an ending.
string
operator
required
How the subject is compared. The allowed operators depend on the subject type.
string
value
Any of:
Any of:
string
number
Array<string>
null
object
kind
required
Marks a group of conditions.
string
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
match
required
Whether all or any of the grouped conditions must match.
string
conditions
required
The grouped conditions. Groups do not nest.
Array<object>
object
kind
required
Marks a single condition.
string
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
subject
required
One of:
object
type
required
What the condition tests.
string
node_public_id
required
Public ID of the question whose answer is tested.
string
object
type
required
What the condition tests.
string
key
required
Key of the Hidden value that is tested.
string
object
type
required
What the condition tests.
string
calculated_value_public_id
required
Public ID of the Calculated value that is tested.
string
object
type
required
What the condition tests.
string
page_public_id
required
Public ID of the page the respondent must have visited.
string
object
type
required
Matches once the respondent reaches an ending.
string
operator
required
How the subject is compared. The allowed operators depend on the subject type.
string
value
Any of:
Any of:
string
number
Array<string>
null
actions
required
What the rule does when it applies, in order.
Array
One of:
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Shows the target. A show target starts hidden until a matching rule shows it.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Hides the target.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Makes the question required.
string
node_public_id
required
Public ID of the question to require.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Makes the question optional.
string
node_public_id
required
Public ID of the question to make optional.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Skips ahead when the respondent advances. Jumps only go forward.
string
to_page_public_id
required
Public ID of a later question page or of an ending.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Sets a number Calculated value from a formula.
string
calculated_value_public_id
required
Public ID of the Calculated value this action updates.
string
formula
required
Arithmetic formula over answers and Calculated values.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Redirects the respondent to a URL after an ending. Needs the Pro plan.
string
url
required
The URL to redirect to. Pipes are allowed.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Updates a text Calculated value.
string
calculated_value_public_id
required
Public ID of the Calculated value this action updates.
string
operation
required
Whether the text replaces the value, is appended to it, or is prepended to it.
string
text
required
The text to write. Pipes are allowed.
string
calculated_values
Calculated values that logic rules update and that pipes and conditions read, in display order. Left out on a draft write, the stored list is kept; send an empty list to remove every entry.
Array<object>
pages
required
Pages in display order. Array order is canonical: the server renumbers page and node order on write.
Array<object>
object
public_id
Public ID of the page (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
name
required
Page name shown in the editor and used by the Form Title block when use_page_name is true.
string
type
required
Page kind: intro, normal, or final. An intro page comes first. Final pages are endings and come last; the first is the Default ending, the others are reached by jump rules.
string
is_hidden
Whether the page is hidden: kept in the draft, skipped by publish validation, and absent from the published form.
boolean
is_entrypoint
Whether respondents start on this page. Always the first page: true on any other page is rejected on write.
boolean
is_auto_jump_next_page
Whether answering the page’s single eligible question advances to the next page automatically. Derived by the server from the page’s blocks; ignored on write.
boolean
nodes
required
Blocks on the page in display order. Layout children reference their row through parent_node_id.
Array
One of: discriminator: type
- actions
- text_input_short
- text_input_long
- text_input_email
- text_input_link
- number_input
- phone_number_input
- file_upload
- switch
- checkbox
- dropdown
- dropdown_multiselect
- multiple_choice
- checkbox_choice
- yes_no
- ranking
- slider
- rating
- rating_number
- nps
- date_picker
- time_picker
- date_time_picker
- date_range_picker
- text
- image
- media
- divider
- layout_row
- matrix
- form_title
- progress_bar
- thank_you
actions
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
label
Text of the page’s primary button.
string
is_page_actions_override
Whether this page overrides the theme’s button behavior (back button, arrows, and alignment).
boolean
back_button_label
Text of the Back button.
string
text_input_short
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
text_input_long
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
text_input_email
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
text_input_link
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
number_input
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
number_minmax
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
phone_number_input
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
file_upload
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
file_upload_accepted_categories
Any of:
Array<string>
null
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
switch
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
checkbox
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
dropdown
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
select_options_data
Selectable options in display order.
Array<object>
object
value
Stable option value stored in answers.
string
label
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_randomize
Whether the options are shuffled for each respondent.
boolean
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
dropdown_multiselect
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
select_options_data
Selectable options in display order.
Array<object>
object
value
Stable option value stored in answers.
string
label
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_randomize
Whether the options are shuffled for each respondent.
boolean
default_value
Any of:
Array<string>
null
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
multiple_choice
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
select_options_data
Selectable options in display order.
Array<object>
object
value
Stable option value stored in answers.
string
label
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_randomize
Whether the options are shuffled for each respondent.
boolean
select_options_selection
Whether respondents pick one option (single) or several (multiple).
string
select_options_layout
Option layout: list, bordered, or inline; applies only when is_select_options_layout_override is true.
string
multiple_choice_variant
Key shown before each option: number or alphabet.
string
default_value
Any of:
Any of:
string
Array<string>
null
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
checkbox_choice
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
select_options_data
Selectable options in display order.
Array<object>
object
value
Stable option value stored in answers.
string
label
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_randomize
Whether the options are shuffled for each respondent.
boolean
select_options_selection
Whether respondents pick one option (single) or several (multiple).
string
select_options_style
Control style of the options: checkbox or radio.
string
select_options_layout
Option layout: list, bordered, or inline; applies only when is_select_options_layout_override is true.
string
default_value
Any of:
Any of:
string
Array<string>
null
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
yes_no
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
select_options_data
Selectable options in display order.
Array<object>
object
value
Stable option value stored in answers.
string
label
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_style
Control style of the options: checkbox or radio.
string
select_options_layout
Option layout: list, bordered, or inline; applies only when is_select_options_layout_override is true.
string
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
ranking
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
select_options_data
Selectable options in display order.
Array<object>
object
value
Stable option value stored in answers.
string
label
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_randomize
Whether the options are shuffled for each respondent.
boolean
select_options_layout
Option layout: list, bordered, or inline; applies only when is_select_options_layout_override is true.
string
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
slider
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
slider_step
Increment between selectable values.
number
slider_minmax
Lowest and highest selectable values.
object
min
Lowest selectable value.
number
max
Highest selectable value.
number
slider_show_value
When the current value is displayed: none, hover, or always.
string
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
rating
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
rating_allow_half
Whether half steps can be selected.
boolean
rating_max
Number of stars on the Rating question.
number
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
rating_number
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
rating_max
Highest selectable Linear Scale value.
number
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
nps
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
date_picker
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
date_format
Display format of dates, for example DD/MM/YYYY.
string
date_range
default_value
Any of:
One of:
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
value
The fixed value used when type is static.
string format: date-time
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
null
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
time_picker
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
time_format
Display format of times: HH:mm or hh:mm A.
string
time_range
time_minute_step
Minute increment offered by the time picker: 1, 5, 10, 15, 30, or 60.
string
default_value
Any of:
One of:
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
value
required
The fixed value used when type is static.
string
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
null
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
date_time_picker
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
date_format
Display format of dates, for example DD/MM/YYYY.
string
date_range
time_format
Display format of times: HH:mm or hh:mm A.
string
time_range
time_minute_step
Minute increment offered by the time picker: 1, 5, 10, 15, 30, or 60.
string
default_value
Any of:
One of:
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
value
The fixed value used when type is static.
string format: date-time
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
null
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
date_range_picker
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
date_format
Display format of dates, for example DD/MM/YYYY.
string
date_range
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
text
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
image
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
image_alignment
Horizontal alignment of the image: left, center, or right.
string
image_full_width
Whether the image stretches to the full form width.
boolean
media
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
media_embed
media_alignment
Horizontal alignment of the embed: left, center, or right.
string
media_full_width
Whether the embed stretches to the full form width.
boolean
divider
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
key
additional properties
layout_row
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
matrix
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
object
select_options_data
Selectable options in display order.
Array<object>
object
value
Stable option value stored in answers.
string
label
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_matrix_rows
Matrix rows in display order; the columns come from select_options_data.
Array<object>
object
value
Stable option value stored in answers.
string
label
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
validation
Answer validation rules. Omitting it on write makes the question required.
object
required
Whether respondents must answer before continuing.
boolean
form_title
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
progress_bar
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
thank_you
object
public_id
Public ID of the node (4 characters). Optional on write: a present ID keeps or matches the item, an absent ID creates a new item with a server-minted ID.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
Type-specific content and settings. Omitted keys receive the current product defaults, which every read echoes back.
settings
Notification settings of the form. A key left out on a draft write keeps its stored value; a key left out on create receives its default.
object
email_notifications_recipients_owner
Email addresses of the organization members who receive the owner email, at most ten. Each must belong to an active member of the organization. Turning owner emails on while the list is empty adds the token owner, as the app does; an empty list sends no owner email.
Array<string>
properties
Behavior and search-engine properties of the form. A key left out on a draft write keeps its stored value; a key left out on create receives its default.
object
access
Whether the form accepts submissions. Read-only: owned by the close, reopen, and access operations.
object
duplicate_response_rule
Any of:
One of:
One completed response per respondent IP address.
object
type
required
The matching method: ip_address, submission_id, or component.
string
One completed response per browser, using the completed response ID saved in it.
object
type
required
The matching method: ip_address, submission_id, or component.
string
Rejects a completed response that repeats an earlier answer to one question. Blank optional answers are not checked.
object
type
required
The matching method: ip_address, submission_id, or component.
string
node_public_id
required
Public ID of the question whose answer must be unique: a visible short text, email, phone, link, or number block on a visible page.
string
null
styles
Theme applied to the form. Only theme_id is writable: on create and on a draft write. Override properties are edited in the app.
object
theme_name
Name of the applied theme. Read-only.
string
override_properties
Any of:
object
font
Font family name.
string
is_form_background_color
is_form_background_blur
page_actions_show_back_button
page_actions_show_button_arrows
select_options_layout
null
Responses
Section titled “Responses”Default Response
Media typeapplication/json
object
public_id
required
Public ID of the form (10 characters). Read-only: assigned by the server on create and ignored on write.
string
name
required
Form name shown in the app.
string
is_template
required
Whether the resource is a Private Template. Read-only on draft writes; honored when creating a form.
boolean
hidden_values
required
logic_rules
required
Conditional logic rules in evaluation order. Rules show, hide, require, or skip to pages, update Calculated values, and redirect (Pro) based on answers, Hidden values, and Calculated values. Rule, condition, and action IDs are 1-22 URL-safe characters chosen by the client and must stay stable.
Array<object>
object
public_id
required
Public ID of the rule, unique within the form. 1-22 URL-safe characters.
string
conditions
required
When the rule applies.
object
match
required
Whether all or any of the items must match. A rule without items always applies.
string
items
required
Conditions and condition groups.
Array
One of:
object
kind
required
Marks a single condition.
string
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
subject
required
One of:
object
type
required
What the condition tests.
string
node_public_id
required
Public ID of the question whose answer is tested.
string
object
type
required
What the condition tests.
string
key
required
Key of the Hidden value that is tested.
string
object
type
required
What the condition tests.
string
calculated_value_public_id
required
Public ID of the Calculated value that is tested.
string
object
type
required
What the condition tests.
string
page_public_id
required
Public ID of the page the respondent must have visited.
string
object
type
required
Matches once the respondent reaches an ending.
string
operator
required
How the subject is compared. The allowed operators depend on the subject type.
string
value
Any of:
Any of:
string
number
Array<string>
null
object
kind
required
Marks a group of conditions.
string
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
match
required
Whether all or any of the grouped conditions must match.
string
conditions
required
The grouped conditions. Groups do not nest.
Array<object>
object
kind
required
Marks a single condition.
string
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
subject
required
One of:
object
type
required
What the condition tests.
string
node_public_id
required
Public ID of the question whose answer is tested.
string
object
type
required
What the condition tests.
string
key
required
Key of the Hidden value that is tested.
string
object
type
required
What the condition tests.
string
calculated_value_public_id
required
Public ID of the Calculated value that is tested.
string
object
type
required
What the condition tests.
string
page_public_id
required
Public ID of the page the respondent must have visited.
string
object
type
required
Matches once the respondent reaches an ending.
string
operator
required
How the subject is compared. The allowed operators depend on the subject type.
string
value
Any of:
Any of:
string
number
Array<string>
null
actions
required
What the rule does when it applies, in order.
Array
One of:
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Shows the target. A show target starts hidden until a matching rule shows it.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Hides the target.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Makes the question required.
string
node_public_id
required
Public ID of the question to require.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Makes the question optional.
string
node_public_id
required
Public ID of the question to make optional.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Skips ahead when the respondent advances. Jumps only go forward.
string
to_page_public_id
required
Public ID of a later question page or of an ending.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Sets a number Calculated value from a formula.
string
calculated_value_public_id
required
Public ID of the Calculated value this action updates.
string
formula
required
Arithmetic formula over answers and Calculated values.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Redirects the respondent to a URL after an ending. Needs the Pro plan.
string
url
required
The URL to redirect to. Pipes are allowed.
string
object
id
required
ID of this item, unique within the rule. 1-22 URL-safe characters.
string
type
required
Updates a text Calculated value.
string
calculated_value_public_id
required
Public ID of the Calculated value this action updates.
string
operation
required
Whether the text replaces the value, is appended to it, or is prepended to it.
string
text
required
The text to write. Pipes are allowed.
string
calculated_values
required
Calculated values that logic rules update and that pipes and conditions read, in display order.
Array<object>
pages
required
Pages in display order. Array order is canonical: the server renumbers page and node order on write.
Array<object>
object
public_id
required
Public ID of the page (4 characters). Always present on read.
string
name
required
Page name shown in the editor and used by the Form Title block when use_page_name is true.
string
type
required
Page kind: intro, normal, or final. An intro page comes first. Final pages are endings and come last; the first is the Default ending, the others are reached by jump rules.
string
is_hidden
required
Whether the page is hidden: kept in the draft, skipped by publish validation, and absent from the published form.
boolean
is_entrypoint
required
Whether respondents start on this page. Always the first page: true on any other page is rejected on write.
boolean
is_auto_jump_next_page
required
Whether answering the page’s single eligible question advances to the next page automatically. Derived by the server from the page’s blocks; ignored on write.
boolean
nodes
required
Blocks on the page in display order. Layout children reference their row through parent_node_id.
Array
One of: discriminator: type
- actions
- text_input_short
- text_input_long
- text_input_email
- text_input_link
- number_input
- phone_number_input
- file_upload
- switch
- checkbox
- dropdown
- dropdown_multiselect
- multiple_choice
- checkbox_choice
- yes_no
- ranking
- slider
- rating
- rating_number
- nps
- date_picker
- time_picker
- date_time_picker
- date_range_picker
- text
- image
- media
- divider
- layout_row
- matrix
- form_title
- progress_bar
- thank_you
actions
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of the page button row.
object
label
required
Text of the page’s primary button.
string
is_page_actions_override
required
Whether this page overrides the theme’s button behavior (back button, arrows, and alignment).
boolean
back_button_label
required
Text of the Back button.
string
text_input_short
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Short Answer question.
object
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
text_input_long
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Long Answer question.
object
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
text_input_email
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of an Email question.
object
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
text_input_link
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Link question.
object
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
number_input
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Number question.
object
number_minmax
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
phone_number_input
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Phone question.
object
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
file_upload
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a File Upload question.
object
file_upload_accepted_categories
Any of:
Array<string>
null
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
switch
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Switch question.
object
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
checkbox
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Checkbox question.
object
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
dropdown
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Dropdown question.
object
select_options_data
required
Selectable options in display order.
Array<object>
object
value
required
Stable option value stored in answers.
string
label
required
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_randomize
required
Whether the options are shuffled for each respondent.
boolean
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
dropdown_multiselect
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Multiselect question.
object
select_options_data
required
Selectable options in display order.
Array<object>
object
value
required
Stable option value stored in answers.
string
label
required
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_randomize
required
Whether the options are shuffled for each respondent.
boolean
default_value
Any of:
Array<string>
null
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
multiple_choice
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Multiple Choice question.
object
select_options_data
required
Selectable options in display order.
Array<object>
object
value
required
Stable option value stored in answers.
string
label
required
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_randomize
required
Whether the options are shuffled for each respondent.
boolean
select_options_selection
Whether respondents pick one option (single) or several (multiple).
string
select_options_layout
Option layout: list, bordered, or inline; applies only when is_select_options_layout_override is true.
string
multiple_choice_variant
required
Key shown before each option: number or alphabet.
string
default_value
Any of:
Any of:
string
Array<string>
null
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
checkbox_choice
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Checkboxes question.
object
select_options_data
required
Selectable options in display order.
Array<object>
object
value
required
Stable option value stored in answers.
string
label
required
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_randomize
required
Whether the options are shuffled for each respondent.
boolean
select_options_selection
Whether respondents pick one option (single) or several (multiple).
string
select_options_style
Control style of the options: checkbox or radio.
string
select_options_layout
Option layout: list, bordered, or inline; applies only when is_select_options_layout_override is true.
string
default_value
Any of:
Any of:
string
Array<string>
null
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
yes_no
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Yes/No question.
object
select_options_data
required
Selectable options in display order.
Array<object>
object
value
required
Stable option value stored in answers.
string
label
required
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_style
Control style of the options: checkbox or radio.
string
select_options_layout
Option layout: list, bordered, or inline; applies only when is_select_options_layout_override is true.
string
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
ranking
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Ranking question.
object
select_options_data
required
Selectable options in display order.
Array<object>
object
value
required
Stable option value stored in answers.
string
label
required
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_randomize
required
Whether the options are shuffled for each respondent.
boolean
select_options_layout
Option layout: list, bordered, or inline; applies only when is_select_options_layout_override is true.
string
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
slider
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Slider question.
object
slider_step
required
Increment between selectable values.
number
slider_minmax
required
Lowest and highest selectable values.
object
min
required
Lowest selectable value.
number
max
required
Highest selectable value.
number
slider_show_value
required
When the current value is displayed: none, hover, or always.
string
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
rating
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Rating question.
object
rating_allow_half
required
Whether half steps can be selected.
boolean
rating_max
required
Number of stars on the Rating question.
number
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
rating_number
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Linear Scale question.
object
rating_max
required
Highest selectable Linear Scale value.
number
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
nps
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Net Promoter Score question.
object
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
date_picker
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Date question.
object
date_format
required
Display format of dates, for example DD/MM/YYYY.
string
date_range
required
default_value
Any of:
One of:
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
value
required
The fixed value used when type is static.
string format: date-time
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
null
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
time_picker
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Time question.
object
time_format
required
Display format of times: HH:mm or hh:mm A.
string
time_range
required
time_minute_step
required
Minute increment offered by the time picker: 1, 5, 10, 15, 30, or 60.
string
default_value
Any of:
One of:
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
value
required
The fixed value used when type is static.
string
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
null
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
date_time_picker
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Date Time question.
object
date_format
required
Display format of dates, for example DD/MM/YYYY.
string
date_range
required
time_format
required
Display format of times: HH:mm or hh:mm A.
string
time_range
required
time_minute_step
required
Minute increment offered by the time picker: 1, 5, 10, 15, 30, or 60.
string
default_value
Any of:
One of:
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
value
required
The fixed value used when type is static.
string format: date-time
object
type
required
Static for a fixed value, relative for the moment the respondent opens the form.
string
null
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
date_range_picker
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Date Range question.
object
date_format
required
Display format of dates, for example DD/MM/YYYY.
string
date_range
required
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
text
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
image
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of an Image block.
object
image_alignment
required
Horizontal alignment of the image: left, center, or right.
string
image_full_width
required
Whether the image stretches to the full form width.
boolean
media
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Media block.
object
media_embed
media_alignment
required
Horizontal alignment of the embed: left, center, or right.
string
media_full_width
required
Whether the embed stretches to the full form width.
boolean
divider
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
A Divider block has no settings; the meta must be an empty object.
object
key
additional properties
layout_row
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
matrix
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
meta
required
Content and settings of a Matrix question.
object
select_options_data
required
Selectable options in display order.
Array<object>
object
value
required
Stable option value stored in answers.
string
label
required
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
select_options_matrix_rows
required
Matrix rows in display order; the columns come from select_options_data.
Array<object>
object
value
required
Stable option value stored in answers.
string
label
required
Option label shown to respondents.
string
label_formatted
Option label as inline rich text HTML; derived from label when omitted.
string
validation
required
Answer validation rules. Omitting it on write makes the question required.
object
required
required
Whether respondents must answer before continuing.
boolean
form_title
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
progress_bar
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
thank_you
object
public_id
required
Public ID of the node (4 characters). Always present on read.
string
sort_order
required
Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.
integer
is_hidden
required
Whether the node is hidden: kept in the draft and absent from the published form.
boolean
type
required
Node type key that selects the meta shape.
string
settings
required
Notification settings of the form. A key left out on a draft write keeps its stored value; a key left out on create receives its default.
object
email_notifications_recipients_owner
required
Email addresses of the organization members who receive the owner email, at most ten. Each must belong to an active member of the organization. Turning owner emails on while the list is empty adds the token owner, as the app does; an empty list sends no owner email.
Array<string>
properties
required
Behavior and search-engine properties of the form. A key left out on a draft write keeps its stored value; a key left out on create receives its default.
object
access
required
Whether the form accepts submissions. Read-only: owned by the close, reopen, and access operations.
object
duplicate_response_rule
required
Any of:
One of:
One completed response per respondent IP address.
object
type
required
The matching method: ip_address, submission_id, or component.
string
One completed response per browser, using the completed response ID saved in it.
object
type
required
The matching method: ip_address, submission_id, or component.
string
Rejects a completed response that repeats an earlier answer to one question. Blank optional answers are not checked.
object
type
required
The matching method: ip_address, submission_id, or component.
string
node_public_id
required
Public ID of the question whose answer must be unique: a visible short text, email, phone, link, or number block on a visible page.
string
null
styles
required
Theme applied to the form. Only theme_id is writable: on create and on a draft write. Override properties are edited in the app.
object
theme_name
Name of the applied theme. Read-only.
string
override_properties
required
Any of:
object
font
Font family name.
string
select_options_layout
null
Example
{ "logic_rules": [ { "conditions": { "match": "all", "items": [ { "kind": "condition", "subject": { "type": "answer" }, "operator": "is" } ] }, "actions": [ { "type": "show", "target": { "kind": "node" } } ] } ], "calculated_values": [ { "type": "number" } ], "pages": [ { "type": "intro", "nodes": [ { "type": "actions", "meta": { "is_page_actions_override": false, "back_button_label": "Back", "action_button_alignment": "left" } } ] } ], "settings": { "email_notifications_enabled_owner": 0, "email_notifications_enabled_respondent": 0 }, "properties": { "show_branding": 0, "auto_jump_next_page": 0, "allow_back_navigation": 0, "meta_index": 0, "partial_response_capture_enabled": 0 }, "access": { "is_closed": 0, "duplicate_response_rule": { "type": "ip_address" } }, "styles": { "override_properties": { "form_width": "xs", "form_size": "xs", "form_spacing": "xs", "form_align_x": "left", "form_align_y": "top", "is_form_background_color": 0, "is_form_background_blur": 0, "border_radius": "none", "border_shadow": "none", "logo_align_x": "left", "is_logo_hidden": 0, "is_logo_full_width": 0, "page_actions_show_back_button": 0, "page_actions_show_button_arrows": 0, "page_actions_alignment": "left", "select_options_layout": "list" } }}Default Response
Media typeapplication/json
object
code
required
The stable code to branch on.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
issues
required
Every value the request got wrong.
Array<object>
object
path
required
The path into the request, with property names and numeric array indexes.
Array
message
required
What is wrong with the value at this path.
string
code
required
The stable code for the issue. Branch on it, and use it with params to write your own text.
string
accepted_values
Accepted values when a node type or enum value is rejected.
Array
Example
{ "code": "INVALID_INPUT"}Default Response
Media typeapplication/json
object
code
required
The stable code to branch on.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
Example
{ "code": "INVALID_INPUT"}A Plan Error: either an exhausted plan limit or a field that needs a larger plan. Branch on code.
Media typeapplication/json
Any of:
object
code
required
The organization is already at a limit its plan sets.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
plan
required
The plan whose limit was applied.
string
upgrade_url
required
Where to review plans and upgrade the organization.
string
limit
required
The limit that blocked the call.
object
key
required
Which plan limit was reached.
string
max
required
What the plan allows.
integer
current
required
What the organization is using right now.
integer
object
code
required
The request sets a field the plan does not include.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
plan
required
The plan whose features were applied.
string
upgrade_url
required
Where to review plans and upgrade the organization.
string
feature
required
The plan feature the blocked field needs, such as meta_tags or partial_response_access.
string
path
required
The path of the blocked field, such as properties/meta_title. On a write it points into the request body; on publish it points into the Draft Document, and it is empty when the blocker is not a document field.
string
Example
{ "code": "PLAN_LIMIT_REACHED", "plan": "free", "limit": { "key": "max_forms" }}Default Response
Media typeapplication/json
object
code
required
The stable code to branch on.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
Example
{ "code": "INVALID_INPUT"}Default Response
Media typeapplication/json
object
code
required
Returned for a form that does not exist, is in Trash, or belongs to another organization. The three are not told apart.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
Example
{ "code": "NOT_FOUND"}Default Response
Media typeapplication/json
object
code
required
The form is archived: it has no editable draft, so draft writes, publish, and conversion are refused.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
Example
{ "code": "FORM_ARCHIVED"}A rejected call. The organization budget names the policy it rejected the call under; the request floor that bounds hammering sends the envelope alone.
Media typeapplication/json
Any of:
object
code
required
The stable code to branch on.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
policy
required
The policy that rejected the call.
string
plan
required
The plan whose numbers were applied.
string
limit
required
The policy limit in credits.
integer
used
required
Credits already spent in the open window.
integer
remaining
required
Credits still available under the policy.
integer
cost
required
What the rejected call would have cost.
integer
window_seconds
required
How long the policy window lasts.
integer
resets_at
required
When the window that rejected the call ends.
string format: date-time
retry_after_seconds
required
Seconds to wait before retrying. Also sent as the Retry-After response header.
integer
object
code
required
The stable code to branch on.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
Example
{ "code": "INVALID_INPUT", "policy": "minute", "plan": "free"}Default Response
Media typeapplication/json
object
code
required
The stable code to branch on.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
Example
{ "code": "INVALID_INPUT"}Default Response
Media typeapplication/json
object
code
required
The requested operation has no available capacity. Retry after the Retry-After header says.
string
message
required
A human-readable explanation. Not part of the contract; never branch on it.
string
request_id
required
The ID of the failed request, also sent as the X-Request-Id response header.
string
retry_after_seconds
required
Seconds to wait before retrying. Also sent as the Retry-After response header.
integer
Example
{ "code": "SERVICE_UNAVAILABLE"}