Matrix and multi-row scales

These question types ask several things in one question: each has a list of rows, and the respondent answers every row. 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
matrix	Matrix	matrix
slider	Slider	numbers_scale
numbers_scale	Number scale	numbers_scale
constant_sum	Constant sum	numbers_scale
semantic_differential	Semantic differential	numbers_scale

matrix

A table: rows are sub-questions, columns are the answers.

Rows and columns

questions holds the rows and choices holds the columns, both in display order. Each item has the same keys.

Key	Type	Description
id	string	12-character identifier. Answers refer to rows and columns by it.
ref	string	Identifier in UUID format.
label	string	Text of the row or column.

Properties

Key	Type	Default	Description
description	string	""	Text under the question title.
matrix_type	string	"single_choice"	Type of answer. What a cell holds. See the table below.

matrix_type	Name in the editor	Each row takes
single_choice	Single answer	One column.
multiple_choice	Multiple selection	Any number of columns.
text	Text answers	A text in every column.
number	Number answers	A number in every column.

Validations

Key	Type	Default	Description
required	boolean	false	Every row needs an answer. With text and number, every cell needs a value.
min_select	integer	""	Min answers. Fewest columns per row. Used with multiple_choice.
max_select	integer	""	Max answers. Most columns per row. Used with multiple_choice.

An empty string or null means no limit. In a matrix that is not required, the limits apply only to the rows the respondent answered.

Example

{
  "id": "Lt6yUw9ZaB3c",
  "ref": "6e8a0c2f-4b17-4d59-c1fe-3a5c7e9b1d46",
  "type": "matrix",
  "title": "How satisfied are you with each area?",
  "properties": { "description": "", "matrix_type": "single_choice" },
  "validations": { "required": true, "min_select": "", "max_select": "" },
  "questions": [
    { "id": "rowSupport01", "ref": "a1c3e5f7-0b29-4d4b-8f6a-1c3e5a7b9d02", "label": "Support" },
    { "id": "rowPricing02", "ref": "b2d4f6a8-1c3a-4e5c-9a7b-2d4f6b8c0e13", "label": "Pricing" }
  ],
  "choices": [
    { "id": "colLow000001", "ref": "c3e5a7b9-2d4b-4f6d-ab8c-3e5a7c9d1f24", "label": "Low" },
    { "id": "colMedium002", "ref": "d4f6b8c0-3e5c-4a7e-bc9d-4f6b8d0e2a35", "label": "Medium" },
    { "id": "colHigh00003", "ref": "e5a7c9d1-4f6d-4b8f-cd0e-5a7c9e1f3b46", "label": "High" }
  ],
  "media": false
}

Answer

matrix has one entry per answered row. A row the respondent left empty is not in the list.

Key	Description
matrix[].id, matrix[].label	id and text of the row.
matrix[].choice	With matrix_type single_choice: a list with the one picked column.
matrix[].choices	With the other three matrix types: a list of the picked or filled columns.
…[].id, …[].label	id and text of the column.
…[].value	true for a picked column. In text and number matrices: the typed value, as a string.

{
  "type": "matrix",
  "matrix": [
    {
      "label": "Support",
      "id": "rowSupport01",
      "choice": [{ "id": "colHigh00003", "label": "High", "value": true }]
    },
    {
      "label": "Pricing",
      "id": "rowPricing02",
      "choice": [{ "id": "colMedium002", "label": "Medium", "value": true }]
    }
  ]
}

Row and column texts are taken from the form as it is now. A row or column that was removed from the form after the response was given is left out.

Rows of the scale questions

slider, numbers_scale, constant_sum and semantic_differential keep their rows in questions.

Key	Type	Description
id	string	12-character identifier. Answers refer to the row by it.
ref	string	Identifier in UUID format.
question	string	Text of the row.
sub_labels	object	Texts at the ends and the middle of the row’s scale: left, center, right. The editor has fields for left and right.

All four types are required by default (validations.required is true in a new question) and all four store the same answer format.

Answer

The answer type is numbers_scale and the rows are in a list named choices. Each item has the id of the row and one more property: the row text is its name and the value is its value.

{
  "type": "numbers_scale",
  "choices": [
    { "Speed": 70, "id": "rowSpeed0001" },
    { "Design": 45, "id": "rowDesign002" }
  ]
}

A semantic_differential row has no text, so there the value is under the fixed name value:

{
  "type": "numbers_scale",
  "choices": [
    { "value": 2, "id": "rowTempo0001" }
  ]
}

Because the row text is a property name, match rows by id: the text changes when the form is edited or translated.

slider

A slider for each row.

Properties

Key	Type	Default	Description
description	string	""	Text under the question title.
type	string	"slider"	Always slider.
randomize	boolean	false	Random order. Rows are shuffled for each respondent.
range.start	integer	0	Lowest value. The editor keeps it at 0.
range.end	integer	100	Size of scale. Highest value, from range.start + 3 up to 100.
slider.start_position	string	"left"	Starting position. Where the handle starts: left (at range.start) or center (the middle of the range).
slider.hide_segments	boolean	false	Hide segments. Hides the marks along the slider.
slider.show_value	boolean	true	Shows the current value above the handle.
hide_questions_labels	boolean	false	Hide labels. Hides the sub_labels of the rows.

Example

{
  "id": "Bn4mCx7VzQ1e",
  "ref": "f6b8d0e2-5a7e-4c90-de1f-6b8d0f2a4c57",
  "type": "slider",
  "title": "How important is each of these to you?",
  "properties": {
    "description": "",
    "type": "slider",
    "randomize": false,
    "range": { "start": 0, "end": 100 },
    "slider": { "show_value": true, "start_position": "left", "hide_segments": false },
    "hide_questions": false,
    "hide_questions_labels": false
  },
  "validations": { "required": true },
  "questions": [
    {
      "id": "rowSpeed0001",
      "ref": "07c9e1f3-6b8f-4da1-ef20-7c9e1a3b5d68",
      "question": "Speed",
      "sub_labels": { "left": "Not important", "center": "", "right": "Very important" }
    }
  ],
  "media": false
}

numbers_scale

A row of number buttons for each row of the question.

Properties

Key	Type	Default	Description
description	string	""	Text under the question title.
type	string	"numbers"	Always numbers.
randomize	boolean	false	Random order.
range.end	integer	5	Number of points. 5 to 10. The buttons run from 1 to this value.
hide_questions_labels	boolean	false	Hide labels. Hides the sub_labels of the rows.
hide_questions	boolean	false	Hide questions. Hides the row texts. The editor offers it when the question has more than one row.

The value of each row in the answer is the number of the picked button.

constant_sum

The respondent spreads a fixed total over the rows, for example 100 points over five features.

Properties

Key	Type	Default	Description
description	string	""	Text under the question title.
randomize	boolean	false	Random order.
total_sum.total	integer	100	Max sum. The total to spread, up to 1000000.
total_sum.unit	string	"pts"	Unit. Shown next to the values, up to 8 characters.
range.end	integer	100	Single scale size. Most a single row can take.
hide_questions_labels	boolean	true	Hides the sub_labels of the rows.

When the question is required, the values of all rows have to add up to exactly total_sum.total. Rows can stay at zero.

semantic_differential

Each row is a scale between two opposite words, for example “Slow” and “Fast”.

Properties

Key	Type	Default	Description
description	string	""	Text under the question title.
type	string	"slider"	Scale type. slider or numbers (buttons).
randomize	boolean	false	Random order.
range.start	integer	1	Lowest value.
range.end	integer	5	Number of points. 5 to 10.
slider.start_position	string	"center"	The handle starts in the middle of the scale.
hide_questions	boolean	true	The rows show only their two words, without a row text.

The two words of a row are sub_labels.left and sub_labels.right. The question text of a row is empty.

{
  "id": "rowTempo0001",
  "ref": "18daf2a4-7c90-4eb2-f031-8d0f2b4c6e79",
  "question": "",
  "sub_labels": { "left": "Slow", "center": "", "right": "Fast" }
}