Choice questions

Questions answered by picking from options. They share the common question keys.

Answer examples show an answer as Get responses returns it and as webhooks send it, without its question part. See Answers.

type	Name in the editor	Answer type
multiple_choice	Choice	choice, or choices with multiple selection
picture_choice	Picture choice	choice, or choices with multiple selection
dropdown	Dropdown	text
yesno	Yes/No	boolean
legal	Legal note	boolean
ranking	Ranking	choices

The choices list

multiple_choice, picture_choice, dropdown and ranking keep their options in choices, in display order.

Key	Type	Description
id	string	12-character identifier of the option.
ref	string	Identifier in UUID format. Logic rules and quotas refer to the option by it. A copy of the question gets new values.
label	string	Text of the option.
media	object	Picture choice only: the image of the option. See Media.

multiple_choice

A list of options with one or several answers.

Properties

Key	Type	Default	Description
description	string	""	Text under the question title.
allow_multiple_selection	boolean	false	Multiple selection. The respondent can pick more than one option.
randomize	boolean	false	Random order. Options are shuffled for each respondent.
allow_other_choice	boolean	false	Other choice. Adds an option with a text field for the respondent’s own answer.
other_choice_label	string	"Other"	Label of that option.
horizontal_alignment	boolean	false	Inline answers. Options are laid out in a row.

Validations

Key	Type	Default	Description
required	boolean	false	The respondent has to answer.
min_select	integer	""	Min. Fewest options to pick. Used with allow_multiple_selection.
max_select	integer	""	Max. Most options to pick, up to the number of options.

An empty string or null means no limit. Setting a limit in the editor also makes the question required.

Example

{
  "id": "Qw8nLr2TzK5p",
  "ref": "c3a9e1b7-5f24-4d68-8e0b-1a7c6d9f2e53",
  "type": "multiple_choice",
  "title": "Which devices do you use?",
  "properties": {
    "description": "Pick up to two.",
    "randomize": false,
    "allow_multiple_selection": true,
    "allow_other_choice": true,
    "other_choice_label": "Other",
    "horizontal_alignment": false
  },
  "validations": { "required": true, "min_select": 1, "max_select": 2 },
  "choices": [
    { "id": "aB3dE6gH9jK2", "ref": "5d2f8c41-9b7e-4a13-a6c0-2e4f6b8d0a17", "label": "Phone" },
    { "id": "mN5pQ8sT1vW4", "ref": "8e1a3c57-0d9f-4b26-b7d1-3f5a7c9e1b28", "label": "Tablet" },
    { "id": "xY7zA0cD3fG6", "ref": "1f4b6d79-2e0a-4c38-c8e2-4a6b8d0f2c39", "label": "Laptop" }
  ],
  "media": false
}

Answer

The answer lists the picked options, each with its id and the label the respondent saw. Its type depends on allow_multiple_selection.

With multiple selection, the type and the key are choices:

{
  "type": "choices",
  "choices": [
    { "label": "Phone", "id": "aB3dE6gH9jK2" },
    { "label": "Smart watch", "id": "other" }
  ]
}

With a single answer, the type and the key are choice. The value is still a list, with one item:

{
  "type": "choice",
  "choice": [
    { "label": "Tablet", "id": "mN5pQ8sT1vW4" }
  ]
}

The option added by allow_other_choice has the id other, and its label is the text the respondent typed.

Quotas

A multiple_choice or picture_choice question can cap how many responses pick each option. Quotas are available when the feature is switched on for the team and for the form (settings.quotas_enabled).

quotas is a list on the question:

Key	Type	Description
answerRef	string	ref of the option.
limit	integer	Number of submitted responses with this option after which it counts as full.
jumpTo	object or null	Where a respondent goes when they submit a full option: { "type": "component", "value": "<question ref>" } or { "type": "end_page", "value": "<end page ref>" }. With null the response is saved as usual.

picture_choice

Options shown as images.

Properties

Key	Type	Default	Description
description	string	""	Text under the question title.
allow_multiple_selection	boolean	false	Multiple selection.
randomize	boolean	false	Random order.
large_thumbs	boolean	false	Bigger image. Shows larger pictures.
hide_labels	boolean	false	Hide labels. Shows the pictures without their text.
zoom_images	boolean	false	Enlarge pictures. Adds a magnifier button that opens the picture larger, with its label. New form version only.

Validations are the same as for multiple_choice: required, min_select, max_select.

Each option carries its image in media:

{
  "id": "rT6uI9oP2aS5",
  "ref": "2a5c7e80-3f1b-4d49-d9f3-5b7c9e1a3d40",
  "label": "Logo A",
  "media": {
    "url": "https://…/logo-a.png",
    "type": "image",
    "scale": 1,
    "pos_x": 0,
    "pos_y": 0,
    "frame": 0
  }
}

Answer

Same format as multiple_choice: choice or choices with the picked options. The answer holds the label of each picked option, not its image.

dropdown

A searchable list with one answer. Use it for long lists.

It has no options of its own in the editor: properties.description and validations.required. Options are in choices.

Answer

The answer is the label of the picked option, as text, in the language the respondent used.

{ "type": "text", "text": "Germany" }

yesno

Two answers: yes or no.

Properties

Key	Type	Default	Description
description	string	""	Text under the question title.
answer_type	string	"thumbs"	Type of answers. How the two answers look: thumbs (thumb up and down icons), check (check mark and cross), emoji (👍 and 👎) or text (buttons with the words).

The words on the buttons come from the form’s messages (yes, no), so they follow the form language.

Validations: required only.

Answer

{ "type": "boolean", "boolean": true }

legal

A consent checkbox, for example for terms or data processing. The question title is the text next to the checkbox.

It has no options of its own: properties.description and validations.required. When the question is required, the respondent has to tick the box to continue.

Answer

A ticked box is stored as true. A box left empty stores no answer.

{ "type": "boolean", "boolean": true }

ranking

The respondent puts the options in order.

Properties

Key	Type	Default	Description
description	string	A hint to drag the answers	Text under the question title.
randomize	boolean	false	Random order. The starting order is shuffled for each respondent.

Validations: required only.

Answer

The answer lists the options in the order the respondent set, first place first. There is no separate rank number: the position in the list is the rank.

{
  "type": "choices",
  "choices": [
    { "label": "Price", "id": "mN5pQ8sT1vW4" },
    { "label": "Quality", "id": "aB3dE6gH9jK2" },
    { "label": "Support", "id": "xY7zA0cD3fG6" }
  ]
}