Pages

A page is one screen of the respondent flow. The pages array of the Form Blueprint lists pages in display order, and each page holds a nodes array. A page’s public_id is optional on write and always present on read, and an omitted is_hidden is false. The server sets is_entrypoint and is_auto_jump_next_page, as described below.

Fields

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

Page types

type is one of three values:

Type	How many	What it holds
intro	At most one	Welcome content, such as a Text node, and an Actions node that starts the form. No questions. It must be the first page: an intro page anywhere else is refused with 400 INVALID_INPUT, with an issue at path ["pages", <index>, "type"].
normal	Any number	Questions and other content, and an Actions node. Publishing needs at least one question on a visible normal page.
final	1 to 10, after every other page	An ending: at least one node, at most one Thank You node, plus text, image, divider, and layout_row content. No questions and no Actions node. Cannot be hidden.

The Docs Example Form uses all three: “Welcome” (intro), “Your details” (normal), and “Thank you” (final).

Endings

A final page is an ending, the screen respondents see after they finish. The first ending is the Default ending: respondents reach it when they continue past the last question page. Other endings are reached only through a jump action.

A draft can hold several endings on any plan. Publishing more than one ending, or an ending with content beyond one Thank You node, needs the Pro plan: a Free organization gets 402 PRO_FEATURE_REQUIRED with feature: "custom_endings" and path: "pages". The editor’s view is in Conditional logic.

Entrypoint

is_entrypoint marks the page respondents start on. It is always the first page in the array, so you never need to send it. Every read shows true on that page and false on the others. Sending true on any other page is refused with 400 INVALID_INPUT, with an issue at path ["pages", <index>, "is_entrypoint"]. To start respondents elsewhere, move that page to the front. The first page cannot be an ending.

Auto-jump

is_auto_jump_next_page shows whether a page qualifies to advance respondents as soon as they answer. The server derives it: it is true on a page that holds exactly one visible question of an eligible type, and false everywhere else. The eligible types are dropdown, checkbox, switch, yes_no, rating, rating_number, nps, and multiple_choice or checkbox_choice with single selection.

The field is read-only and ignored on write, so a document you write back can read a different value after its questions change. The setting you control is the form-wide properties.auto_jump_next_page. Auto-jump navigation describes the respondent experience.

Ordering

Array order is canonical. Each page leads to the next one in the array, the last question page leads to the Default ending, and an ending ends the form. There is no next-page field to maintain: logic rules change the path with jump, show, and hide actions.

Every read lists pages in the order the editor’s page list shows them, and a write stores the array order exactly as reordering pages in the editor does. The Draft Document, the Published Document, Publish Issue paths, CSV exports, notification emails, and workflow answers all use that one order. For a form whose stored order is irregular, for example one an older client left with a page linked to two next pages, the order is resolved as in the editor: it starts at the entrypoint, prefers a question page over an ending when a page links to both, and places pages that no link reaches after the others, question pages before endings. The next updateFormDraft stores the array you send as a plain sequence again.

Hidden pages

A page with is_hidden: true stays in the draft with all of its nodes, is skipped by Publish Validation, and is stripped from the published document. If the first page is hidden, the next visible page becomes the entrypoint at publish. An ending cannot be hidden, and publishing is blocked when no page besides the endings is visible. See Hidden pages and nodes.

Example

The “Your details” page of the Docs Example Form draft: four visible questions, one hidden question (nCmp), and the Actions node that submits the form.

The Your details page of the draft document

{
  "public_id": "pQ01",
  "name": "Your details",
  "type": "normal",
  "is_hidden": false,
  "is_entrypoint": false,
  "is_auto_jump_next_page": false,
  "nodes": [
    {
      "public_id": "nNam",
      "parent_node_id": null,
      "column_index": null,
      "sort_order": 1,
      "is_hidden": false,
      "type": "text_input_short",
      "meta": {
        "question": "<span>Full name</span>",
        "placeholder": "Jane Doe",
        "validation": {
          "required": true
        }
      }
    },
    {
      "public_id": "nEml",
      "parent_node_id": null,
      "column_index": null,
      "sort_order": 2,
      "is_hidden": false,
      "type": "text_input_email",
      "meta": {
        "question": "<span>Email address</span>",
        "placeholder": "[email protected]",
        "validation": {
          "required": true
        }
      }
    },
    {
      "public_id": "nTck",
      "parent_node_id": null,
      "column_index": null,
      "sort_order": 3,
      "is_hidden": false,
      "type": "multiple_choice",
      "meta": {
        "question": "<span>Ticket type</span>",
        "select_options_data": [
          {
            "value": "general",
            "label": "General",
            "label_formatted": "<span>General</span>"
          },
          {
            "value": "student",
            "label": "Student",
            "label_formatted": "<span>Student</span>"
          },
          {
            "value": "speaker",
            "label": "Speaker",
            "label_formatted": "<span>Speaker</span>"
          }
        ],
        "select_options_randomize": false,
        "select_options_selection": "single",
        "multiple_choice_variant": "alphabet",
        "validation": {
          "required": true
        }
      }
    },
    {
      "public_id": "nDie",
      "parent_node_id": null,
      "column_index": null,
      "sort_order": 4,
      "is_hidden": false,
      "type": "checkbox_choice",
      "meta": {
        "question": "<span>Dietary needs</span>",
        "select_options_data": [
          {
            "value": "vegetarian",
            "label": "Vegetarian",
            "label_formatted": "<span>Vegetarian</span>"
          },
          {
            "value": "vegan",
            "label": "Vegan",
            "label_formatted": "<span>Vegan</span>"
          },
          {
            "value": "gluten_free",
            "label": "Gluten-free",
            "label_formatted": "<span>Gluten-free</span>"
          }
        ],
        "select_options_randomize": false,
        "select_options_selection": "single",
        "select_options_style": "checkbox",
        "validation": {
          "required": false
        }
      }
    },
    {
      "public_id": "nCmp",
      "parent_node_id": null,
      "column_index": null,
      "sort_order": 5,
      "is_hidden": true,
      "type": "text_input_short",
      "meta": {
        "question": "<span>Company</span>",
        "validation": {
          "required": false
        }
      }
    },
    {
      "public_id": "nSub",
      "parent_node_id": null,
      "column_index": null,
      "sort_order": 6,
      "is_hidden": false,
      "type": "actions",
      "meta": {
        "label": "Register",
        "is_page_actions_override": false,
        "back_button_label": "Back"
      }
    }
  ]
}

Publish Issues that concern pages

Publish Validation reports these codes for page structure. An issue about one page carries its page_public_id. Errors describes the envelope.

Most of these shapes are already refused by a draft write, so you meet them mainly on forms edited in the app.

Code	Meaning
FORM_PUBLISH_MISSING_FINAL_PAGE	The form has no ending.
FORM_PUBLISH_MULTIPLE_FINAL_PAGES	The form has more than ten endings.
FORM_PUBLISH_FINAL_PAGE_POSITION	A page that is not an ending comes after the first ending.
FORM_PUBLISH_FINAL_PAGE_HIDDEN	An ending is hidden.
FORM_PUBLISH_ALL_PAGES_HIDDEN	Every page besides the endings is hidden.
FORM_PUBLISH_FINAL_PAGE_NODES	An ending is empty, holds a question, or holds more than one Thank You node.
FORM_PUBLISH_THANK_YOU_PLACEMENT	A Thank You node sits on a page that is not an ending.
FORM_PUBLISH_MISSING_QUESTION	No visible normal page holds a question.
FORM_PUBLISH_BLUEPRINT_INVALID	The form has more than one intro page, an intro page is not the first page, or an intro page holds a question.
FORM_PUBLISH_MULTIPLE_ENTRYPOINTS	More than one page is marked as the entrypoint.
FORM_PUBLISH_ENTRYPOINT_FINAL_PAGE	An ending is marked as the entrypoint.
FORM_PUBLISH_ENTRYPOINT_POSITION	The entrypoint is not the first page that is not an ending.
FORM_PUBLISH_AUTO_JUMP_INVALID	A page enables auto-jump without exactly one eligible question.
FORM_PUBLISH_TOO_MANY_PAGES	The form has more than 100 pages.