The Responses API lets you retrieve the responses to your typeforms on demand and in JSON format. Let's take a look at each object in a Responses payload for a typeform with four responses.
First, here's what a complete JSON response for our example typeform looks like:
{
"total_items": 4,
"page_count": 1,
"items": [
{
"landing_id": "21085286190ffad1248d17c4135ee56f",
"token": "21085286190ffad1248d17c4135ee56f",
"landed_at": "2017-09-14T22:33:59Z",
"submitted_at": "2017-09-14T22:38:22Z",
"metadata": {
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/603.3.8 (KHTML, like Gecko) Version/10.1.2 Safari/603.3.8",
"platform": "other",
"referer": "https://user_id.typeform.com/to/lR6F4j",
"network_id": "responsdent_network_id",
"browser": "default"
},
"answers": [
{
"field": {
"id": "hVONkQcnSNRj",
"type": "dropdown",
"ref": "my_custom_dropdown_reference"
},
"type": "text",
"text": "Job opportunities"
},
{
"field": {
"id": "RUqkXSeXBXSd",
"type": "yes_no",
"ref": "my_custom_yes_no_reference"
},
"type": "boolean",
"boolean": false
},
{
"field": {
"id": "gFFf3xAkJKsr",
"type": "legal",
"ref": "my_custom_legal_reference"
},
"type": "boolean",
"boolean": true
},
{
"field": {
"id": "JwWggjAKtOkA",
"type": "short_text",
"ref": "my_custom_short_text_reference"
},
"type": "text",
"text": "Lian"
},
{
"field": {
"id": "SMEUb7VJz92Q",
"type": "email",
"ref": "my_custom_email_reference"
},
"type": "email",
"email": "lian1078@other.com"
},
{
"field": {
"id": "pn48RmPazVdM",
"type": "number",
"ref": "my_custom_number_reference"
},
"type": "number",
"number": 1
},
{
"field": {
"id": "Q7M2XAwY04dW",
"type": "number",
"ref": "my_custom_number2_reference"
},
"type": "number",
"number": 1
},
{
"field": {
"id": "WOTdC00F8A3h",
"type": "rating",
"ref": "my_custom_rating_reference"
},
"type": "number",
"number": 3
},
{
"field": {
"id": "DlXFaesGBpoF",
"type": "long_text",
"ref": "my_custom_long_text_reference"
},
"type": "text",
"text": "It's a big, busy city. I moved here for a job, but I like it, so I am planning to stay. I have made good friends here."
},
{
"field": {
"id": "NRsxU591jIW9",
"type": "opinion_scale",
"ref": "my_custom_opinion_scale_reference"
},
"type": "number",
"number": 1
},
{
"field": {
"id": "PNe8ZKBK8C2Q",
"type": "picture_choice",
"ref": "my_custom_picture_choice_reference"
},
"type": "choices",
"choices": {
"labels": ["New York", "Tokyo"]
}
},
{
"field": {
"id": "KoJxDM3c6x8h",
"type": "date",
"ref": "my_custom_date_reference"
},
"type": "date",
"date": "2012-03-20T00:00:00Z"
},
{
"field": {
"id": "ceIXxpbP3t2q",
"type": "multiple_choice",
"ref": "my_custom_multiple_choice_reference"
},
"type": "choice",
"choice": {
"label": "A friend's experience in Sydney"
}
},
{
"field": {
"id": "k6TP9oLGgHjl",
"type": "multiple_choice",
"ref": "my_custom_multiple_choice2_reference"
},
"type": "choice",
"choice": {
"label": "Tokyo"
}
},
{
"field": {
"id": "K4tBip2OUqNQ",
"type": "phone_number",
"ref": "phone_number"
},
"type": "phone_number",
"phone_number": "+14151234567"
}
],
"hidden": {},
"calculated": {
"score": 2
},
"variables": [
{
"key": "score",
"type": "number",
"number": 2
},
{
"key": "name",
"type": "text",
"text": "typeform"
}
]
},
{
"landing_id": "610fc266478b41e4927945e20fe54ad2",
"token": "610fc266478b41e4927945e20fe54ad2",
"landed_at": "2017-09-14T22:27:38Z",
"submitted_at": "2017-09-14T22:33:56Z",
"metadata": {
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"platform": "other",
"referer": "https://user_id.typeform.com/to/lR6F4j",
"network_id": "responsdent_network_id",
"browser": "default"
},
"answers": [
{
"field": {
"id": "k6TP9oLGgHjl",
"type": "multiple_choice",
"ref": "my_custom_multiple_choice2_reference"
},
"type": "choice",
"choice": {
"label": "New York"
}
},
{
"field": {
"id": "X4BgU2f1K6tG",
"type": "file_upload",
"ref": "my_custom_file_upload_reference"
},
"type": "file_url",
"file_url": "https://admin.typeform.com/form/lT9Z2j/field/X4BgU2f1K6tG/results/afd8258fd453-aerial_view_rural_city_latvia_valmiera_urban_district_48132860.jpg/download"
},
{
"field": {
"id": "ceIXxpbP3t2q",
"type": "multiple_choice",
"ref": "my_custom_multiple_choice_reference"
},
"type": "choice",
"choice": {
"label": "Other"
}
},
{
"field": {
"id": "hVONkQcnSNRj",
"type": "dropdown",
"ref": "my_custom_dropdown_reference"
},
"type": "text",
"text": "Cost of living"
},
{
"field": {
"id": "JwWggjAKtOkA",
"type": "short_text",
"ref": "my_custom_short_text_reference"
},
"type": "text",
"text": "Sarah"
},
{
"field": {
"id": "RUqkXSeXBXSd",
"type": "yes_no",
"ref": "my_custom_yes_no_reference"
},
"type": "boolean",
"boolean": true
},
{
"field": {
"id": "Fep7sEoBsnvC",
"type": "long_text",
"ref": "my_custom_long_text2_reference"
},
"type": "text",
"text": "I read a magazine article about traveling to Sydney"
},
{
"field": {
"id": "gFFf3xAkJKsr",
"type": "legal",
"ref": "my_custom_legal_reference"
},
"type": "boolean",
"boolean": true
},
{
"field": {
"id": "BFcpoPU5yJPM",
"type": "short_text",
"ref": "my_custom_short_text2_reference"
},
"type": "text",
"text": "San Francisco"
},
{
"field": {
"id": "SMEUb7VJz92Q",
"type": "email",
"ref": "my_custom_email_reference"
},
"type": "email",
"email": "sarahbsmith@example.com"
},
{
"field": {
"id": "pn48RmPazVdM",
"type": "number",
"ref": "my_custom_number_reference"
},
"type": "number",
"number": 1
},
{
"field": {
"id": "WOTdC00F8A3h",
"type": "rating",
"ref": "my_custom_rating_reference"
},
"type": "number",
"number": 3
},
{
"field": {
"id": "Q7M2XAwY04dW",
"type": "number",
"ref": "my_custom_number2_reference"
},
"type": "number",
"number": 3
},
{
"field": {
"id": "DlXFaesGBpoF",
"type": "long_text",
"ref": "my_custom_long_text_reference"
},
"type": "text",
"text": "It's a rural area. Very quiet. There are a lot of farms...farming is the major industry here."
},
{
"field": {
"id": "NRsxU591jIW9",
"type": "opinion_scale",
"ref": "my_custom_opinion_scale_reference"
},
"type": "number",
"number": 1
},
{
"field": {
"id": "KoJxDM3c6x8h",
"type": "date",
"ref": "my_custom_date_reference"
},
"type": "date",
"date": "2016-05-13T00:00:00Z"
},
{
"field": {
"id": "PNe8ZKBK8C2Q",
"type": "picture_choice",
"ref": "my_custom_picture_choice_reference"
},
"type": "choices",
"choices": {
"labels": ["London", "New York"]
}
},
{
"field": {
"id": "K4tBip2OUqNQ",
"type": "phone_number",
"ref": "phone_number"
},
"type": "phone_number",
"phone_number": "+33612345678"
}
],
"hidden": {},
"calculated": {
"score": 4
},
"variables": [
{
"key": "score",
"type": "number",
"number": 4
}
]
},
{
"landing_id": "9ba5db11ec6c63d22f08aade805bd363",
"token": "9ba5db11ec6c63d22f08aade805bd363",
"landed_at": "2017-09-14T22:24:49Z",
"submitted_at": "2017-09-14T22:27:34Z",
"metadata": {
"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_2_1 like Mac OS X) AppleWebKit/602.4.6 (KHTML, like Gecko) Version/10.0 Mobile/14D27 Safari/602.1",
"platform": "other",
"referer": "https://user_id.typeform.com/to/lR6F4j",
"network_id": "responsdent_network_id",
"browser": "default"
},
"answers": [
{
"field": {
"id": "RUqkXSeXBXSd",
"type": "yes_no",
"ref": "my_custom_yes_no_reference"
},
"type": "boolean",
"boolean": false
},
{
"field": {
"id": "gFFf3xAkJKsr",
"type": "legal",
"ref": "my_custom_legal_reference"
},
"type": "boolean",
"boolean": true
},
{
"field": {
"id": "JwWggjAKtOkA",
"type": "short_text",
"ref": "my_custom_short_text_reference"
},
"type": "text",
"text": "Paolo"
},
{
"field": {
"id": "pn48RmPazVdM",
"type": "number",
"ref": "my_custom_number_reference"
},
"type": "number",
"number": 5
},
{
"field": {
"id": "Q7M2XAwY04dW",
"type": "number",
"ref": "my_custom_number2_reference"
},
"type": "number",
"number": 5
},
{
"field": {
"id": "PNe8ZKBK8C2Q",
"type": "picture_choice",
"ref": "my_custom_picture_choice_reference"
},
"type": "choices",
"choices": {
"labels": ["Barcelona", "Sydney"]
}
},
{
"field": {
"id": "WOTdC00F8A3h",
"type": "rating",
"ref": "my_custom_rating_reference"
},
"type": "number",
"number": 5
},
{
"field": {
"id": "DlXFaesGBpoF",
"type": "long_text",
"ref": "my_custom_long_text_reference"
},
"type": "text",
"text": "I live in a medium-sized European city. It's not too crowded, and the people are nice. I like the weather. It's also easy to travel to many beautiful and interesting vacation destinations from where I live."
},
{
"field": {
"id": "NRsxU591jIW9",
"type": "opinion_scale",
"ref": "my_custom_opinion_scale_reference"
},
"type": "number",
"number": 4
},
{
"field": {
"id": "KoJxDM3c6x8h",
"type": "date",
"ref": "my_custom_date_reference"
},
"type": "date",
"date": "1999-08-01T00:00:00Z"
},
{
"field": {
"id": "k6TP9oLGgHjl",
"type": "multiple_choice",
"ref": "my_custom_multiple_choice2_reference"
},
"type": "choice",
"choice": {
"label": "Barcelona"
}
},
{
"field": {
"id": "K4tBip2OUqNQ",
"type": "phone_number",
"ref": "phone_number"
},
"type": "phone_number",
"phone_number": "+14151234567"
}
],
"hidden": {},
"calculated": {
"score": 10
},
"variables": [
{
"key": "score",
"type": "number",
"number": 10
}
]
},
{
"landing_id": "5fcb3f9c162e1fcdaadff4405b741080",
"token": "5fcb3f9c162e1fcdaadff4405b741080",
"landed_at": "2017-09-15T09:09:30Z",
"submitted_at": "0001-01-01T00:00:00Z",
"metadata": {
"user_agent": "Mozilla/5.0 (Linux; Android 4.1.2; GT-N7000 Build/JZO54K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/55.0.2883.91 Mobile Safari/537.36",
"platform": "other",
"referer": "https://user_id.typeform.com/to/lR6F4j",
"network_id": "responsdent_network_id",
"browser": "default"
},
"answers": null,
"hidden": {},
"calculated": {
"score": 0
},
"variables": [
{
"key": "score",
"type": "number",
"number": 0
}
]
}
]
}Our example has three completed responses and one landing without a response (which means the person opened but didn't complete the typeform). Now, let's dig in to each object.
NOTE: The Responses API payload and general data is different than the general form data and descriptions you'll see in the Create API.
At the top of each Responses payload, you'll see total_items, page_count, and items.
"total_items": 4,
"page_count": 1,
"items": [total_items is the number of responses your request retrieved.page_count is the number of pages in the payload.items is an array of objects that make up the responses to your typeform. Each response is one item.Each response to your typeform is listed as a separate item in the payload. Each item starts with a general data object that includes information about the response and respondent.
{
"landing_id": "21085286190ffad1248d17c4135ee56f",
"token": "21085286190ffad1248d17c4135ee56f",
"landed_at": "2017-09-14T22:33:59Z",
"submitted_at": "2017-09-14T22:38:22Z",
"metadata": {
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/603.3.8 (KHTML, like Gecko) Version/10.1.2 Safari/603.3.8",
"platform": "other",
"referer": "https://user_id.typeform.com/to/lR6F4j",
"network_id": "responsdent_network_id",
"browser": "default"
},This general data object lists information like the landing and submission time, the user agent string (which tells you which device and browser the respondent used), the typeform's URL, and the respondent's network ID.
NOTE: The landing_id and token values are the same.
Next, each response in the payload includes the answers array. Each answers array object lists four pieces of information:
NOTE: The answers array lists objects in random order, not in the same order as the questions appear in your typeform. Also, answers arrays for multiple responses do not necessarily list objects in the same order in each response. Use the id values in each object to match answers to questions.
Here's an example answers array object for the question "What is your first name?" (which is a short text question):
"answers": [
{
"field": {
"id": "JwWggjAKtOkA",
"type": "short_text",
"ref": "my_custom_short_text_reference"
},
"type": "text",
"text": "Lian"
},
...answers array objects start with a field object with these key-value pairs:
| Key | Value |
|---|---|
| id | The unique ID for the question. |
| type | The question type, such as short_text, email, or opinion_scale. You can see a complete list of question types in the POST https://api.typeform.com/forms endpoint. |
| ref | The readable name you specified for the field when you created the form. Use the ref value to match answers with questions. The Responses payload will not include ref fields unless you specified them when you created the form. |
Then, answers array objects list the answer type, which means type of data accepted as an answer, such as text, choice, number, or rating.
The next line lists the value for the type, followed by the respondent's answer. In this example, the short_text question type accepts text answers, and the text answer for this question is Lian.
Here's how question type and answer type match up:
Question type | Answer type | Field with answer value (relative to response item object) |
|---|---|---|
| short_text | text | answers[n].text |
| long_text | text | answers[n].text |
| dropdown | text | answers[n].text |
| multiple_choice (single option) | choice | answers[n].choice.label |
| multiple_choice (multiple options) | choices | answers[n].choices.labels |
| picture_choice (single option) | choice | answers[n].choice.label |
| picture_choice (multiple options) | choices | answers[n].choices.labels |
| answers[n].email | ||
| website | url | answers[n].url |
| file_upload | file_url | answers[n].file_url |
| legal | boolean | answers[n].boolean |
| yes_no | boolean | answers[n].boolean |
| rating | number | answers[n].number |
| opinion_scale | number | answers[n].number |
| number | number | answers[n].number |
| date | date | answers[n].date |
| payment | payment | answers[n].payment |
The answers array object for a yes_no question looks like this:
{
"field": {
"id": "RUqkXSeXBXSd",
"type": "yes_no",
"ref": "my_custom_yes_no_reference"
},
"type": "boolean",
"boolean": true
},And for a rating question:
{
"field": {
"id": "WOTdC00F8A3h",
"type": "rating",
"ref": "my_custom_rating_reference"
},
"type": "number",
"number": 3
},And for a file_upload question:
"field": {
"id": "X4BgU2f1K6tG",
"type": "file_upload",
"ref": "my_custom_file_upload_reference"
},
"type": "file_url",
"file_url": "https://admin.typeform.com/form/lT9Z2j/field/X4BgU2f1K6tG/results/afd8258fd453-aerial_view_rural_city_latvia_valmiera_urban_district_48132860.jpg/download"
},NOTE: Do not rely on file_url having a certain structure or shape - it is subject to change. To access file information for a file obtained using file_url from a webhook payload, you can rely on the Content-Disposition header. It is not currently possible to reliably access file information for a file obtained using a file_url from a Results API payload.
The final object in each response lists any Hidden Field and calculated values. In this example, our typeform doesn't use Hidden Fields (so that object is empty}, but it does include a calculated score:
"hidden": {},
"calculated": {
"score": 4
}"variables": [
{
"key": "score",
"type": "number",
"number": 4
},
{
"key": "name",
"type": "text",
"text": "typeform"
}
]If someone opens your typeform but doesn't complete it, your payload will include an object that lists all the general data, with a null value for the answers array and no Hidden Fields or calculated score values:
{
"landing_id": "5fcb3f9c162e1fcdaadff4405b741080",
"token": "5fcb3f9c162e1fcdaadff4405b741080",
"landed_at": "2017-09-15T09:09:30Z",
"submitted_at": "0001-01-01T00:00:00Z",
"metadata": {
"user_agent": "Mozilla/5.0 (Linux; Android 4.1.2; GT-N7000 Build/JZO54K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/55.0.2883.91 Mobile Safari/537.36",
"platform": "other",
"referer": "https://user_id.typeform.com/to/lR6F4j",
"network_id": "responsdent_network_id",
"browser": "default"
},
"answers": null,
"hidden": {},
"calculated": {
"score": 0
}Ready to retrieve a typeform's responses? You can write an application or call the Responses API directly with a personal access token.
Or, head straight to the Responses reference documentation.