Form structure

A Responsly form is stored as one JSON document, the form definition. The editor writes it, and the form that respondents open is drawn from it. This reference describes that document: the question types and their options, pages, logic, variables, hidden fields, settings and themes, and the format of the answers a form produces.

Where you meet it in the API

You want	Use
The definition of a form	Get workspaces. Each form in the result carries its definition.
The answers to a form	Get responses or a webhook. Each answer names the question’s type and has a format that depends on it. See Answers.
Data of your own in a response	Hidden fields, passed in the form link.

Note

The API reads forms. It does not create or change them: forms are built in the editor. This reference documents the format so that you can read a definition, understand the answers you receive and prepare links, hidden fields and end page addresses that work with your systems.

Parts of a definition

Key	Type	Holds	Described in
settings	object	Name, language, schedule, access, display and other form-level options.	Settings
theme	object	A reference to the theme: { "ref": "…" }.	Themes
welcome_pages	array	No page or one page shown before the questions.	Welcome and end pages
components	array	The questions, in order.	Question types
end_pages	array	One page or more shown after the response is submitted.	Welcome and end pages
logic	array	Jumps between pages and calculations.	Logic
variables	array	Names of the numbers the form works out.	Variables and scoring
hidden	array	Names of the hidden fields.	Hidden fields

Translations and the texts of buttons and messages are stored next to the definition, per language. See Languages.

A small form

{
  "settings": {
    "name": "Order feedback",
    "language": "en",
    "is_public": true
  },
  "theme": { "ref": "D5kvGYdZ" },
  "welcome_pages": [
    {
      "ref": "7e2b9c14-5d3a-4f86-a1c7-0b4d6e8f2a59",
      "title": "Tell us about your order",
      "properties": { "description": "", "button_text": "Start", "align": "center" },
      "media": false
    }
  ],
  "components": [
    {
      "id": "Xe5gHu8JiM2o",
      "ref": "4b6d8f0a-1c93-4e25-a7db-2f4c6e8a0d35",
      "type": "opinion_scale",
      "title": "How likely are you to recommend us to a friend or colleague?",
      "properties": {
        "description": "",
        "icon": "numbers",
        "icon_count": 11,
        "labels": ["Not likely at all", "", "Extremely likely"]
      },
      "validations": { "required": true },
      "media": false
    },
    {
      "id": "Zr4kQ1xYb7Lm",
      "ref": "0f6c2d1e-8a47-4b6f-9c11-3f5a7d2e9b40",
      "type": "text",
      "title": "What is the main reason for your score?",
      "properties": { "description": "", "multiple_lines": true },
      "validations": { "required": false },
      "media": false
    }
  ],
  "end_pages": [
    {
      "ref": "c41d7a90-2e6b-4b35-9f08-6a1c3e5d7b92",
      "title": "Thank you!",
      "properties": { "description": "", "align": "center", "show_button": false },
      "media": false
    }
  ],
  "logic": [],
  "variables": [],
  "hidden": ["user_id"]
}

How a form runs

1. Welcome page. Shown first when the form has one. A password, when set, is asked for here.
2. Pages. Each item of components is one page: a single question, or a group with several questions. The form checks validations before the respondent can leave a page.
3. Logic. When the respondent leaves a page, the form applies the calculations of that page and then looks for a jump. Without a jump, the next page follows.
4. Submit. After the last page, or on a jump to an end page, the response is saved. Webhooks and notifications are sent at this point.
5. End page. The first end page is shown, or the one a rule or a quota chose.

Answers given so far are saved while the form is being filled in, so an abandoned form leaves a partial response in the results. Partial responses are not returned by Get responses and trigger no webhook.

Identifiers

Questions, options and rows carry two identifiers, id and ref. Responses refer to things by id. The form itself, in logic rules, inserted values and translations, refers to them by ref. See id and ref.

Forms and themes are identified by short encoded strings such as D5kvGYdZ.

Limits

Limit	Value
Size of a definition	2 MB
Length of one text	10000 characters
Markup	Not accepted. Texts use formatting marks, and a definition with HTML tags or script addresses is refused.

What depends on the plan

Feature	Lowest plan
File upload question	Essential
Own end page text and media, more than one end page	Essential
Logic and calculations	Essential
Schedule, response limit, password, one response per user	Essential
Randomization	Essential
E-mail notifications	Essential
Hidden fields	Professional
End page button and automatic redirect	Professional
Own logo, tracking tags, link preview, A/B testing	Professional

Basic is the free plan. Links in form texts are available from Essential.

In this reference

Question types All 24 types, their options and validations.

Answers The format of a response and of every answer type.

Logic Jumps, conditions and operators.

Hidden fields Carry your own data into a response.