Answers

This page describes what you receive when a form is answered. Get responses and webhooks use the same format for a response and for each answer.

Response

Key	Type	Description
id	string	Identifier of the response. See Response identifiers.
answers	array or null	One item per answered question, in the order of the form.
hidden	array or null	Hidden fields of the response.
variables	array or null	Variables of the response.

answers, hidden and variables are null, not an empty list, when there is nothing to return.

Get responses returns a list of these objects in items. A webhook sends one of them under payload:

{
  "payload": {
    "answers": [
      {
        "question": { "id": "VlD8orUBcVuK", "title": "How would you rate our customer service?", "type": "customer_sat" },
        "type": "number",
        "number": "5"
      }
    ],
    "hidden": [{ "name": "user_id", "value": "42" }],
    "variables": [{ "name": "score", "value": 5 }],
    "id": "k3J9xQ2mWc7Lp0aZtR5vYb8N1dHf4GsE"
  }
}

What a response contains:

• Only finished responses. A response that was started and not submitted is not returned by Get responses and triggers no webhook.
• Only questions that were answered. A question the respondent skipped, or never saw because of logic, has no item.
• Questions as they are in the form now. Titles come from the current form, and an answer to a question that has since been deleted is left out.
• Questions of a group as separate items. The group itself does not appear.
• No statement. A statement stores no answer.

Response identifiers

The id differs between the two channels:

Channel	id
Get responses	An encoded identifier of the response, about 40 characters.
Webhook	The token of the response, 32 characters. This is also what {{response:id}} inserts into an end page address.

The two values identify the same response but are not equal, so do not use one to look up the other.

Answer

Every answer has the same frame:

{
  "question": { "id": "<question id>", "title": "<question title>", "type": "<question type>" },
  "type": "<answer type>",
  "<value key>": "<value>"
}

Key	Description
question.id	id of the question in the form. It stays the same when the title changes, so use it to recognise a question.
question.title	Title of the question as stored, with its formatting marks and placeholders.
question.type	The question type.
type	The answer type. It tells you which key holds the value.

Answer types

type	Value key	Question types
text	text	text, dropdown
number	number	number, rating, customer_sat, opinion_scale
mail	mail	mail
website	website	website
phone_number	phone_number	phone_number
date	date	date
boolean	boolean	yesno, legal
choice	choice	multiple_choice, picture_choice with a single answer
choices	choices	multiple_choice, picture_choice with multiple selection; ranking
matrix	matrix	matrix
numbers_scale	choices	slider, numbers_scale, constant_sum, semantic_differential
file_url	file_url, file_urls	file_upload, signature

The examples below leave out the question part.

text

{ "type": "text", "text": "Fast delivery, friendly support." }

For a dropdown, text is the label of the picked option in the language the respondent used.

number

{ "type": "number", "number": "9" }

The value is a string. Convert it before you calculate with it. rating and customer_sat give 1 to the number of points, opinion_scale gives 0 to 10.

mail, website, phone_number

{ "type": "mail", "mail": "anna@example.com" }

{ "type": "website", "website": "example.com" }

{ "type": "phone_number", "phone_number": "+14155550132" }

A website is stored as the respondent typed it, with or without https://. A phone number is in international format, with the country calling code.

date

{ "type": "date", "date": "24/03/2027" }

Day first: DD/MM/YYYY. It is not an ISO 8601 date.

boolean

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

true is yes, or a ticked consent box. false is no. A legal question that was left unticked has no answer.

choice and choices

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

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

• choice is used when the question takes a single answer. Its value is a list with one item.
• choices is used when the question allows multiple selection, and for every ranking.
• id is the id of the option in the form. label is the text the respondent saw, in their language.
• The “Other” option has the id other, and its label is the text the respondent typed.
• For a ranking, the order of the list is the ranking, first place first.

Note

Handle both keys. A question can be switched between a single answer and multiple selection, and its answers then arrive under the other key.

matrix

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

One item per answered row, with the row’s id and label. The columns are under choice when the matrix takes a single answer per row, and under choices for multiple selection, text and number matrices. value is true for a picked column, or the typed text or number as a string.

numbers_scale

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

One item per row. The row text is the name of the property that holds the value. For a semantic_differential, whose rows have no text, the property is named value:

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

Read the value by taking the property that is not id, and match rows by id.

file_url

{
  "type": "file_url",
  "file_url": "https://app.responsly.com/form/AbCd1234/file/9f2c7a1e/get",
  "file_urls": [
    "https://app.responsly.com/form/AbCd1234/file/9f2c7a1e/get",
    "https://app.responsly.com/form/AbCd1234/file/3b8d5e0c/get"
  ]
}

file_urls lists every uploaded file. file_url is the first of them. A signature is one PNG file.

Note

The addresses do not expire. A file opens for a signed-in Responsly user who can edit the form.

Hidden fields

"hidden": [
  { "name": "user_id", "value": "42" },
  { "name": "lang", "value": "de" }
]

A list of name and value pairs. Values are text. Besides the hidden fields declared in the form, the list can hold fields the form adds itself, such as lang.

Variables

"variables": [
  { "name": "score", "value": 7 }
]

A list of name and value pairs. Values are numbers, rounded to two decimal places. See Variables and scoring.

Reading answers safely

• Recognise questions by question.id and options, rows and columns by id. Titles and labels change when the form is edited or translated.
• Switch on type and ignore types you do not know. New question types and answer types are added over time.
• Treat answers, hidden and variables as optional: each can be null.
• Expect numbers as strings in number answers.