Read the draft document

GET

/v1/forms/{form_public_id}/draft

const url = 'https://platform.fomr.io/v1/forms/example/draft';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://platform.fomr.io/v1/forms/example/draft \
  --header 'Authorization: Bearer <token>'

Reads the Draft Document: the whole form as it stands in the editor, hidden pages and blocks included, with every ID and default filled in. The response carries a weak ETag equal to the draft hash; keep it to tell whether the draft moved under you. A draft that cannot be published reads fine. Needs forms:read or templates:read. Costs 1 API credit.

Authorizations

bearerAuth

Parameters

Path Parameters

form_public_id

required

string

>= 10 characters <= 10 characters /^[A-Za-z0-9_-]+$/

The public ID of the form or Private Template.

Responses

200

Default Response

application/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

>= 10 characters <= 10 characters /^[A-Za-z0-9_-]+$/

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

Hidden value declarations that respondents can supply through URL parameters.

Array<object>

<= 50 items

object

key

required

Key of the hidden value: lowercase letters, digits, underscores, and hyphens, starting with a letter.

string

>= 1 characters <= 100 characters /^[a-z][a-z0-9_-]*$/

default_value

Any of:

string
null

string

<= 500 characters

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>

<= 100 items

object

public_id

required

Public ID of the rule, unique within the form. 1-22 URL-safe characters.

string

>= 1 characters <= 22 characters /^[A-Za-z0-9_-]+$/

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

Allowed values: all any

items

required

Conditions and condition groups.

Array

One of:

object
object

object

kind

required

Marks a single condition.

string

Allowed value: condition

required

ID of this item, unique within the rule. 1-22 URL-safe characters.

string

>= 1 characters <= 22 characters /^[A-Za-z0-9_-]+$/

subject

required

One of:

object

type

required

What the condition tests.

string

Allowed value: answer

node_public_id

required

Public ID of the question whose answer is tested.

string

>= 1 characters <= 22 characters /^[A-Za-z0-9_-]+$/

operator

required

How the subject is compared. The allowed operators depend on the subject type.

string

Allowed values: is is_not contains not_contains starts_with ends_with is_empty is_not_empty eq neq gt gte lt lte is_any_of is_none_of is_all_of is_true is_false is_before is_after was_visited was_not_visited

value

Any of:

unknown
null

Any of:

string

<= 500 characters

actions

required

What the rule does when it applies, in order.

Array

<= 20 items

One of:

object

required

ID of this item, unique within the rule. 1-22 URL-safe characters.

string

>= 1 characters <= 22 characters /^[A-Za-z0-9_-]+$/

type

required

Shows the target. A show target starts hidden until a matching rule shows it.

string

Allowed value: show

target

required

One of:

object
object

object

kind

required

Targets one block.

string

Allowed value: node

node_public_id

required

Public ID of the block to show or hide.

string

>= 1 characters <= 22 characters /^[A-Za-z0-9_-]+$/

calculated_values

required

Calculated values that logic rules update and that pipes and conditions read, in display order.

Array<object>

<= 50 items

object

public_id

required

Public ID of the Calculated value, unique within the form. 1-22 URL-safe characters.

string

>= 1 characters <= 22 characters /^[A-Za-z0-9_-]+$/

name

required

Name shown in the editor and in formulas. Unique within the form.

string

>= 1 characters <= 50 characters

type

required

Whether the value holds a number or text.

string

Allowed values: number text

initial_value

Any of:

string
null

string

<= 500 characters

pages

required

Pages in display order. Array order is canonical: the server renumbers page and node order on write.

Array<object>

>= 1 items <= 100 items

object

public_id

required

Public ID of the page (4 characters). Always present on read.

string

>= 4 characters <= 4 characters /^[A-Za-z0-9_-]+$/

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

Allowed values: intro normal final

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

<= 101 items

One of: discriminator: type

actions

object

public_id

required

Public ID of the node (4 characters). Always present on read.

string

>= 4 characters <= 4 characters /^[A-Za-z0-9_-]+$/

parent_node_id

required

Any of:

string
null

string

>= 4 characters <= 4 characters /^[A-Za-z0-9_-]+$/

column_index

required

Any of:

integer
null

integer

<= 2

sort_order

required

Position among siblings in the same parent and column. Array order is canonical: the server renumbers from 1.

integer

> 0 <= 9007199254740991

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

Allowed value: actions

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

show_back_button

Any of:

boolean
null

boolean

back_button_label

required

Text of the Back button.

string

default: Back

show_button_arrows

Any of:

boolean
null

boolean

action_button_alignment

Any of:

string
null

string

Allowed values: left center right justify

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_enabled_owner

required

Any of:

number
null

number

Allowed values: 0 1

email_notifications_enabled_respondent

required

Any of:

number
null

number

Allowed values: 0 1

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>

<= 10 items

email_notifications_recipient_respondent

required

Any of:

string
null

string

>= 4 characters <= 4 characters /^[A-Za-z0-9_-]+$/

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

show_branding

required

Any of:

number
null

number

Allowed values: 0 1

auto_jump_next_page

required

Any of:

number
null

number

Allowed values: 0 1

allow_back_navigation

required

Any of:

number
null

number

Allowed values: 0 1

meta_title

required

Any of:

string
null

string

<= 255 characters

meta_description

required

Any of:

string
null

string

<= 500 characters

meta_index

required

Any of:

number
null

number

Allowed values: 0 1

meta_favicon_url

required

Any of:

string
null

string format: uri

<= 1000 characters

meta_ogimage_url

required

Any of:

string
null

string format: uri

<= 1000 characters

partial_response_capture_enabled

required

Any of:

number
null

number

Allowed values: 0 1

access

required

Whether the form accepts submissions. Read-only: owned by the close, reopen, and access operations.

object

is_closed

required

Any of:

number
null

number

Allowed values: 0 1

close_at

required

Any of:

string
null

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$/

open_at

required

Any of:

string
null

string format: date-time

duplicate_response_rule

required

Any of:

object
null

One of:

One completed response per respondent IP address.

object

type

required

The matching method: ip_address, submission_id, or component.

string

Allowed value: ip_address

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_id

required

Any of:

string
null

string

theme_name

Name of the applied theme. Read-only.

string

override_properties

required

Any of:

object
null

object

font

Font family name.

string

background_color

Any of:

string
null

string

/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/

background_url

Any of:

string
null

string format: uri

<= 1000 characters

text_color

Any of:

string
null

string

/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/

secondary_text_color

Any of:

string
null

string

/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/

primary_color

Any of:

string
null

string

option_colors

Any of:

string
null

string

primary_text_color

Any of:

string
null

string

/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/

border_color

Any of:

string
null

string

/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/

shadow_color

Any of:

string
null

string

/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/

dimmed_color

Any of:

string
null

string

/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/

error_color

Any of:

string
null

string

/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/

input_background_color

Any of:

string
null

string

/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/

input_text_color

Any of:

string
null

string

/^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/

form_width

Any of:

string
null

string

Allowed values: xs sm md lg xl

form_size

Any of:

string
null

string

Allowed values: xs sm md lg xl

form_spacing

Any of:

string
null

string

Allowed values: xs sm md lg xl

form_align_x

Any of:

string
null

string

Allowed values: left center right

form_align_y

Any of:

string
null

string

Allowed values: top center

is_form_background_color

Any of:

unknown
null

Any of:

number
null

number

Allowed values: 0 1

is_form_background_blur

Any of:

unknown
null

Any of:

number
null

number

Allowed values: 0 1

border_radius

Any of:

string
null

string

Allowed values: none small full

border_shadow

Any of:

string
null

string

Allowed values: none small large

logo_url

Any of:

string
null

string format: uri

<= 1000 characters

logo_align_x

Any of:

string
null

string

Allowed values: left center right

is_logo_hidden

Any of:

unknown
null

Any of:

number
null

number

Allowed values: 0 1

logo_width

Any of:

integer
null

integer

>= 32 <= 4096

is_logo_full_width

Any of:

unknown
null

Any of:

number
null

number

Allowed values: 0 1

page_actions_show_back_button

Any of:

unknown
null

Any of:

number
null

number

Allowed values: 0 1

page_actions_show_button_arrows

Any of:

unknown
null

Any of:

number
null

number

Allowed values: 0 1

page_actions_alignment

Any of:

string
null

string

Allowed values: left center right justify

select_options_layout

Any of:

string
null

Option layout: list, bordered, or inline; applies only when is_select_options_layout_override is true.

string

Allowed values: list bordered inline

font_id

Any of:

string
null

string

<= 100 characters

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"
    }
  }
}

400

Default Response

application/json

object

code

required

The stable code to branch on.

string

Allowed values: INVALID_INPUT UNAUTHORIZED PERSONAL_ACCESS_TOKEN_EXPIRED PERSONAL_ACCESS_TOKEN_REVOKED PLAN_LIMIT_REACHED PRO_FEATURE_REQUIRED FORBIDDEN FORM_PUBLISH_EMAIL_UNVERIFIED ORGANIZATION_MEMBER_BLOCKED PERSONAL_ACCESS_TOKEN_NOT_PERMITTED NOT_FOUND FORM_NOT_PUBLISHED NO_DRAFT_DURING_PUBLISH FORM_ARCHIVED FORM_CONVERSION_BLOCKED FORM_PUBLISH_REVISION_CONFLICT PAYLOAD_TOO_LARGE FORM_PUBLISH_VALIDATION_FAILED FORM_SAFETY_REJECTED TOO_MANY_REQUESTS API_COOLDOWN SERVER AI_SERVICE_UNAVAILABLE SERVICE_UNAVAILABLE

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

params

The values the message was built from, keyed by name, for clients that write their own text for each code.

object

key

additional properties

Any of:

string
number

string

Example

{
  "code": "INVALID_INPUT"
}

401

Default Response

application/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"
}

403

Default Response

application/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

required_permission

required

Any of:

string
null

string

Example

{
  "code": "INVALID_INPUT"
}

404

Default Response

application/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

Allowed value: NOT_FOUND

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"
}

429

A rejected call. The organization budget names the policy it rejected the call under; the request floor that bounds hammering sends the envelope alone.

application/json

Any of:

object
object

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

Allowed values: minute burst

plan

required

The plan whose numbers were applied.

string

Allowed values: free pro

limit

required

The policy limit in credits.

integer

>= -9007199254740991 <= 9007199254740991

used

required

Credits already spent in the open window.

integer

>= -9007199254740991 <= 9007199254740991

remaining

required

Credits still available under the policy.

integer

>= -9007199254740991 <= 9007199254740991

cost

required

What the rejected call would have cost.

integer

>= -9007199254740991 <= 9007199254740991

window_seconds

required

How long the policy window lasts.

integer

>= -9007199254740991 <= 9007199254740991

cooldown_until

required

Any of:

string
null

string format: date-time

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

>= -9007199254740991 <= 9007199254740991

upgrade_url

required

Any of:

string
null

string

Example

{
  "code": "INVALID_INPUT",
  "policy": "minute",
  "plan": "free"
}

500

Default Response

application/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"
}

Read the draft document

Authorizations

Parameters

Path Parameters

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

429

Example

500

Example

Your next form could be the best-looking thing on your site.