Responses

Retrieve responses

get
https://api.typeform.com/forms/{form_id}/responses

Returns form responses and date and time of form landing and submission.

Request

Query Parameters

page_size
integer

Maximum number of responses. Default value is 25. Maximum value is 1000. If your typeform has fewer than 1000 responses, you can retrieve all of the responses in a single request by adding the page_size parameter. If your typeform has more than 1000 responses, use the since/until or before/after query parameters to narrow the scope of your request.

since
string

Limit request to responses submitted since the specified date and time, inclusive. Could be passed as int (timestamp in seconds) or in ISO 8601 format, UTC time, to the second, with T as a delimiter between the date and time (2020-03-20T14:00:59).

until
string

Limit request to responses submitted until the specified date and time, inclusive. Could be passed as int (timestamp in seconds) or in ISO 8601 format, UTC time, to the second, with T as a delimiter between the date and time (2020-03-20T14:00:59).

after
string

Limit request to responses submitted after the specified token, exclusive. Could not be used together with sort parameter, as it sorts responses in the order that our system processed them (submitted_at). This ensures that you can traverse the complete set of responses without repeating entries.

before
string

Limit request to responses submitted before the specified token, exclusive. Could not be used together with sort parameter, as it sorts responses in the order that our system processed them (submitted_at). This ensures that you can traverse the complete set of responses without repeating entries.

included_response_ids
string

Limit request to the specified response_id values. Use a comma-separated list to specify more than one response_id value.

excluded_response_ids
string

Comma-separated list of response_ids to be excluded from the response.

response_type
array of array

Limit responses to only those which are of the provided response type (started, partial, completed). It is expected to be passed as a comma separated list of values, e.g. response_type=partial,completed. This parameter changes since/until filter, so if completed responses are requested it will filter by submitted_at, if partial responses are requested it will filter by staged_at, otherwise - landed_at. Default value is completed.

completed
boolean

This query param is deprecated, please use response_type param instead. Limit responses to only those which were started (completed=false), but not completed (completed=true) (the respondent did not submit their answers). When completed=false, the responses do not have answers, hidden or calculate members. This parameter changes since/until filter, so if completed=true, it will filter by submitted_at, otherwise - landed_at. Default value is completed=true.

sort
string

Responses order in {fieldID},{asc|desc} format. You can use built-in submitted_at/landed_at field IDs or any field ID from your typeform, possible directions are asc/desc. Default value is submitted_at,desc.

query
string

Limit request to only responses that include the specified string. The string will be escaped and it will be matched against all answers fields, hidden fields and variables values.

fields
array of array

Show only specified fields in answers section. If response does not have answers for specified fields, there will be null. Use a comma-separated list to specify more than one field value.

answered_fields
array of array

Limit request to only responses that include the specified fields in answers section. Use a comma-separated list to specify more than one field value - response will contain at least one of the specified fields.

Path Parameters

form_id
, required

Unique ID for the form. Find in your form URL. For example, in the URL "https://mysite.typeform.com/to/u6nXL7" the form_id is u6nXL7.

Response

Status

200 OK

Schema

Representation of collection of responses to a specific form. It is used for displaying results in a human-friendly format.

total_items
number

Total number of items in the retrieved collection.

page_count
number

Number of pages.

items
array of object

Example

{
  "items": [
    {
      "answers": [
        {
          "field": {
            "id": "hVONkQcnSNRj",
            "ref": "my_custom_dropdown_reference",
            "type": "dropdown"
          },
          "text": "Job opportunities",
          "type": "text"
        },
        {
          "boolean": false,
          "field": {
            "id": "RUqkXSeXBXSd",
            "ref": "my_custom_yes_no_reference",
            "type": "yes_no"
          },
          "type": "boolean"
        },
        {
          "boolean": true,
          "field": {
            "id": "gFFf3xAkJKsr",
            "ref": "my_custom_legal_reference",
            "type": "legal"
          },
          "type": "boolean"
        },
        {
          "field": {
            "id": "JwWggjAKtOkA",
            "ref": "my_custom_short_text_reference",
            "type": "short_text"
          },
          "text": "Lian",
          "type": "text"
        },
        {
          "email": "lian1078@other.com",
          "field": {
            "id": "SMEUb7VJz92Q",
            "ref": "my_custom_email_reference",
            "type": "email"
          },
          "type": "email"
        },
        {
          "field": {
            "id": "pn48RmPazVdM",
            "ref": "my_custom_number_reference",
            "type": "number"
          },
          "number": 1,
          "type": "number"
        },
        {
          "field": {
            "id": "Q7M2XAwY04dW",
            "ref": "my_custom_number2_reference",
            "type": "number"
          },
          "number": 1,
          "type": "number"
        },
        {
          "field": {
            "id": "WOTdC00F8A3h",
            "ref": "my_custom_rating_reference",
            "type": "rating"
          },
          "number": 3,
          "type": "number"
        },
        {
          "field": {
            "id": "DlXFaesGBpoF",
            "ref": "my_custom_long_text_reference",
            "type": "long_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.",
          "type": "text"
        },
        {
          "field": {
            "id": "NRsxU591jIW9",
            "ref": "my_custom_opinion_scale_reference",
            "type": "opinion_scale"
          },
          "number": 1,
          "type": "number"
        },
        {
          "choices": {
            "labels": [
              "New York",
              "Tokyo"
            ]
          },
          "field": {
            "id": "PNe8ZKBK8C2Q",
            "ref": "my_custom_picture_choice_reference",
            "type": "picture_choice"
          },
          "type": "choices"
        },
        {
          "date": "2012-03-20T00:00:00Z",
          "field": {
            "id": "KoJxDM3c6x8h",
            "ref": "my_custom_date_reference",
            "type": "date"
          },
          "type": "date"
        },
        {
          "choice": {
            "label": "A friend's experience in Sydney"
          },
          "field": {
            "id": "ceIXxpbP3t2q",
            "ref": "my_custom_multiple_choice_reference",
            "type": "multiple_choice"
          },
          "type": "choice"
        },
        {
          "choices": {
            "labels": [
              "New York",
              "Tokyo"
            ]
          },
          "field": {
            "id": "abISxvbD5t1p",
            "ref": "my_custom_ranking_reference",
            "type": "ranking"
          },
          "type": "choices"
        },
        {
          "choice": {
            "label": "Tokyo"
          },
          "field": {
            "id": "k6TP9oLGgHjl",
            "ref": "my_custom_multiple_choice2_reference",
            "type": "multiple_choice"
          },
          "type": "choice"
        }
      ],
      "calculated": {
        "score": 2
      },
      "hidden": {},
      "landed_at": "2017-09-14T22:33:59Z",
      "landing_id": "21085286190ffad1248d17c4135ee56f",
      "metadata": {
        "browser": "default",
        "network_id": "respondent_network_id",
        "platform": "other",
        "referer": "https://user_id.typeform.com/to/lR6F4j",
        "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"
      },
      "response_id": "21085286190ffad1248d17c4135ee56f",
      "submitted_at": "2017-09-14T22:38:22Z",
      "token": "test21085286190ffad1248d17c4135ee56f",
      "variables": [
        {
          "key": "score",
          "number": 2,
          "type": "number"
        },
        {
          "key": "name",
          "text": "typeform",
          "type": "text"
        }
      ]
    },
    {
      "answers": [
        {
          "choice": {
            "label": "New York"
          },
          "field": {
            "id": "k6TP9oLGgHjl",
            "ref": "my_custom_multiple_choice2_reference",
            "type": "multiple_choice"
          },
          "type": "choice"
        },
        {
          "field": {
            "id": "X4BgU2f1K6tG",
            "ref": "my_custom_file_upload_reference",
            "type": "file_upload"
          },
          "file_url": "https://api.typeform.com/forms/lT9Z2j/responses/7f46165474d11ee5836777d85df2cdab/fields/X4BgU2f1K6tG/files/afd8258fd453-aerial_view_rural_city_latvia_valmiera_urban_district_48132860.jpg",
          "type": "file_url"
        },
        {
          "choice": {
            "label": "Other"
          },
          "field": {
            "id": "ceIXxpbP3t2q",
            "ref": "my_custom_multiple_choice_reference",
            "type": "multiple_choice"
          },
          "type": "choice"
        },
        {
          "field": {
            "id": "hVONkQcnSNRj",
            "ref": "my_custom_dropdown_reference",
            "type": "dropdown"
          },
          "text": "Cost of living",
          "type": "text"
        },
        {
          "field": {
            "id": "JwWggjAKtOkA",
            "ref": "my_custom_short_text_reference",
            "type": "short_text"
          },
          "text": "Sarah",
          "type": "text"
        },
        {
          "boolean": true,
          "field": {
            "id": "RUqkXSeXBXSd",
            "ref": "my_custom_yes_no_reference",
            "type": "yes_no"
          },
          "type": "boolean"
        },
        {
          "field": {
            "id": "Fep7sEoBsnvC",
            "ref": "my_custom_long_text_reference",
            "type": "long_text"
          },
          "text": "I read a magazine article about travelling to Sydney",
          "type": "text"
        },
        {
          "boolean": true,
          "field": {
            "id": "gFFf3xAkJKsr",
            "ref": "my_custom_legal_reference",
            "type": "legal"
          },
          "type": "boolean"
        },
        {
          "field": {
            "id": "BFcpoPU5yJPM",
            "ref": "my_custom_short_text_reference",
            "type": "short_text"
          },
          "text": "San Francisco",
          "type": "text"
        },
        {
          "email": "sarahbsmith@example.com",
          "field": {
            "id": "SMEUb7VJz92Q",
            "ref": "my_custom_email_reference",
            "type": "email"
          },
          "type": "email"
        },
        {
          "field": {
            "id": "pn48RmPazVdM",
            "ref": "my_custom_number_reference",
            "type": "number"
          },
          "number": 1,
          "type": "number"
        },
        {
          "field": {
            "id": "WOTdC00F8A3h",
            "ref": "my_custom_rating_reference",
            "type": "rating"
          },
          "number": 3,
          "type": "number"
        },
        {
          "field": {
            "id": "Q7M2XAwY04dW",
            "ref": "my_custom_number2_reference",
            "type": "number"
          },
          "number": 3,
          "type": "number"
        },
        {
          "field": {
            "id": "DlXFaesGBpoF",
            "ref": "my_custom_long_text_reference",
            "type": "long_text"
          },
          "text": "It's a rural area. Very quiet. There are a lot of farms...farming is the major industry here.",
          "type": "text"
        },
        {
          "field": {
            "id": "NRsxU591jIW9",
            "ref": "my_custom_opinion_scale_reference",
            "type": "opinion_scale"
          },
          "number": 1,
          "type": "number"
        },
        {
          "date": "2016-05-13T00:00:00Z",
          "field": {
            "id": "KoJxDM3c6x8h",
            "ref": "my_custom_date_reference",
            "type": "date"
          },
          "type": "date"
        },
        {
          "choices": {
            "labels": [
              "London",
              "New York"
            ]
          },
          "field": {
            "id": "PNe8ZKBK8C2Q",
            "ref": "my_custom_picture_choice_reference",
            "type": "picture_choice"
          },
          "type": "choices"
        }
      ],
      "calculated": {
        "score": 4
      },
      "hidden": {},
      "landed_at": "2017-09-14T22:27:38Z",
      "landing_id": "610fc266478b41e4927945e20fe54ad2",
      "metadata": {
        "browser": "default",
        "network_id": "respondent_network_id",
        "platform": "other",
        "referer": "https://user_id.typeform.com/to/lR6F4j",
        "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"
      },
      "submitted_at": "2017-09-14T22:33:56Z",
      "token": "test610fc266478b41e4927945e20fe54ad2"
    },
    {
      "answers": [
        {
          "boolean": false,
          "field": {
            "id": "RUqkXSeXBXSd",
            "ref": "my_custom_yes_no_reference",
            "type": "yes_no"
          },
          "type": "boolean"
        },
        {
          "boolean": true,
          "field": {
            "id": "gFFf3xAkJKsr",
            "ref": "my_custom_legal_reference",
            "type": "legal"
          },
          "type": "boolean"
        },
        {
          "field": {
            "id": "JwWggjAKtOkA",
            "ref": "my_custom_short_text_reference",
            "type": "short_text"
          },
          "text": "Paolo",
          "type": "text"
        },
        {
          "field": {
            "id": "pn48RmPazVdM",
            "ref": "my_custom_number_reference",
            "type": "number"
          },
          "number": 5,
          "type": "number"
        },
        {
          "field": {
            "id": "Q7M2XAwY04dW",
            "ref": "my_custom_number2_reference",
            "type": "number"
          },
          "number": 5,
          "type": "number"
        },
        {
          "choices": {
            "labels": [
              "Barcelona",
              "Sydney"
            ]
          },
          "field": {
            "id": "PNe8ZKBK8C2Q",
            "ref": "my_custom_picture_choice_reference",
            "type": "picture_choice"
          },
          "type": "choices"
        },
        {
          "field": {
            "id": "WOTdC00F8A3h",
            "ref": "my_custom_rating_reference",
            "type": "rating"
          },
          "number": 5,
          "type": "number"
        },
        {
          "field": {
            "id": "DlXFaesGBpoF",
            "ref": "my_custom_long_text_reference",
            "type": "long_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.",
          "type": "text"
        },
        {
          "field": {
            "id": "NRsxU591jIW9",
            "ref": "my_custom_opinion_scale_reference",
            "type": "opinion_scale"
          },
          "number": 4,
          "type": "number"
        },
        {
          "date": "1999-08-01T00:00:00Z",
          "field": {
            "id": "KoJxDM3c6x8h",
            "ref": "my_custom_date_reference",
            "type": "date"
          },
          "type": "date"
        },
        {
          "choice": {
            "label": "Barcelona"
          },
          "field": {
            "id": "k6TP9oLGgHjl",
            "ref": "my_custom_multiple_choice_reference",
            "type": "multiple_choice"
          },
          "type": "choice"
        }
      ],
      "calculated": {
        "score": 10
      },
      "hidden": {},
      "landed_at": "2017-09-14T22:24:49Z",
      "landing_id": "9ba5db11ec6c63d22f08aade805bd363",
      "metadata": {
        "browser": "default",
        "network_id": "respondent_network_id",
        "platform": "other",
        "referer": "https://user_id.typeform.com/to/lR6F4j",
        "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"
      },
      "submitted_at": "2017-09-14T22:27:34Z",
      "token": "test9ba5db11ec6c63d22f08aade805bd363"
    },
    {
      "answers": [],
      "calculated": {
        "score": 0
      },
      "hidden": {},
      "landed_at": "2017-09-15T09:09:30Z",
      "landing_id": "5fcb3f9c162e1fcdaadff4405b741080",
      "metadata": {
        "browser": "default",
        "network_id": "respondent_network_id",
        "platform": "other",
        "referer": "https://user_id.typeform.com/to/lR6F4j",
        "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"
      },
      "submitted_at": "0001-01-01T00:00:00Z",
      "token": "test5fcb3f9c162e1fcdaadff4405b741080"
    }
  ],
  "page_count": 1,
  "total_items": 4
}