> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://typeform.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://typeform.ferndocs.com/_mcp/server. # Retrieve responses GET https://api.typeform.com/forms/{form_id}/responses Returns form responses and date and time of form landing and submission. Reference: https://typeform.ferndocs.com/documentation/responses-api/api-reference/list ## Authentication - `Authorization` header (bearer token, required) — Bearer token authentication. Tokens can be generated from the user account. Privileges needed may vary. - `Authorization` header (required) — A string representation of JWT containing at least two parameters: `ctx.user_id` — user's id `ctx.account_id` — user's default account id `ctx.account_uid` — user's default account uid The usage of account_(u)id from JWT is discouraged, user can have access to multiple accounts, every endpoint has to be account aware if it's needed. This JWT must be signed by the appropriate authority. ## Request ### Path parameters - `form_id` (any, 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`. ### Query parameters - `page_size` (long, optional) — 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, optional) — 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, optional) — 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, optional) — 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, optional) — 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, optional) — 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, optional) — Comma-separated list of `response_id`s to be excluded from the response. - `response_type` (list of string, optional) — 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, optional) — _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, optional) — 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, optional) — 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` (list of string, optional) — 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` (list of string, optional) — 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. ## Response ### 200 OK - `total_items` (double, optional) — Total number of items in the retrieved collection. - `page_count` (double, optional) — Number of pages. - `items` (list of ResponsesItemsItems, optional) ## Errors ### 400 Bad Request Error Bad request - `code` (string, optional) — A developer-readable snake_case key, indicating some idea of what type of error occurred. - `description` (string, optional) — A developer-readable description of the error, expanding on the terse code. - `details` (list of FormsFormIdResponsesGetResponsesContentApplicationJsonSchemaDetailsItems, optional) — An optional object containing more detailed info regarding which field the error occurred in. - `help` (string, optional) — A URL linking to help content, to aid the client developer in resolving the error. This value should be provided whenever available. ### 401 Unauthorized Error Unauthorized - `code` (string, optional) — A developer-readable snake_case key, indicating some idea of what type of error occurred. - `description` (string, optional) — A developer-readable description of the error, expanding on the terse code. - `details` (list of FormsFormIdResponsesGetResponsesContentApplicationJsonSchemaDetailsItems, optional) — An optional object containing more detailed info regarding which field the error occurred in. - `help` (string, optional) — A URL linking to help content, to aid the client developer in resolving the error. This value should be provided whenever available. ### 405 Method Not Allowed Error Method not allowed - `code` (string, optional) — A developer-readable snake_case key, indicating some idea of what type of error occurred. - `description` (string, optional) — A developer-readable description of the error, expanding on the terse code. - `details` (list of FormsFormIdResponsesGetResponsesContentApplicationJsonSchemaDetailsItems, optional) — An optional object containing more detailed info regarding which field the error occurred in. - `help` (string, optional) — A URL linking to help content, to aid the client developer in resolving the error. This value should be provided whenever available. ### 500 Internal Server Error Internal server error - `code` (string, optional) — A developer-readable snake_case key, indicating some idea of what type of error occurred. - `description` (string, optional) — A developer-readable description of the error, expanding on the terse code. - `details` (list of FormsFormIdResponsesGetResponsesContentApplicationJsonSchemaDetailsItems, optional) — An optional object containing more detailed info regarding which field the error occurred in. - `help` (string, optional) — A URL linking to help content, to aid the client developer in resolving the error. This value should be provided whenever available. ## Types ### ResponsesItemsItems Complete form submission as stored in the database. Contains metadata, landing information, and the submitted answers. - `answers` (list of ResponsesItemsItemsAnswersItems, optional) - `calculated` (ResponsesItemsItemsCalculated, optional) - `definition` (ResponsesItemsItemsDefinition, optional) — Subset of a complete form definition to be included with a submission. - `hidden` (ResponsesItemsItemsHidden, optional) - `landed_at` (string, optional) — Time of the form landing. In ISO 8601 format, UTC time, to the second, with T as a delimiter between the date and time. - `landing_id` (string, optional) — Deprecated; now `response_id`. - `metadata` (ResponsesItemsItemsMetadata, optional) — Metadata about a client's HTTP request. - `response_id` (string, optional) — Unique ID for the response. Note that `response_id` values are unique per form but are not unique globally. - `submitted_at` (string, optional) — Time that the form response was submitted. In ISO 8601 format, UTC time, to the second, with T as a delimiter between the date and time. - `variables` (list of ResponsesItemsItemsVariablesItems, optional) ### FormsFormIdResponsesGetResponsesContentApplicationJsonSchemaDetailsItems - `code` (string, optional) — A developer-readable snake_case key, indicating some idea of what type of error occurred. - `description` (string, optional) — A developer-readable description about the field-level error. - `field` (string, optional) — Which field the error occurred. This could refer to a field in the request body, request header, or query parameter. - `help` (string, optional) — A URL linking to help content, to aid the client developer in resolving the error. This value should be provided whenever available. - `in` (enum, optional) — The type of field that caused the error. - Allowed values: `header`, `body`, `query` ### ResponsesItemsItemsAnswersItems A sum of all fields that may occur in an answer. Based on the field type, different properties are required. - `type` (enum, required) — The answer-field's type. - Allowed values: `choice`, `choices`, `date`, `email`, `url`, `file_url`, `number`, `boolean`, `text`, `payment`, `choice`, `choices`, `date`, `email`, `url`, `file_url`, `number`, `boolean`, `text`, `payment`, `choice`, `choices`, `date`, `email`, `url`, `file_url`, `number`, `boolean`, `text`, `payment`, `choice`, `choices`, `date`, `email`, `url`, `file_url`, `number`, `boolean`, `text`, `payment` - `boolean` (boolean, optional) - `choice` (ResponsesItemsItemsAnswersItemsChoice, optional) — Represents single choice answers for dropdown-like fields. - `choices` (ResponsesItemsItemsAnswersItemsChoices, optional) — Represents multiple choice answers. - `date` (string, optional) - `email` (string, optional) - `field` (ResponsesItemsItemsAnswersItemsField, optional) - `file_url` (string, optional) - `number` (double, optional) - `payment` (ResponsesItemsItemsAnswersItemsPayment, optional) - `text` (string, optional) - `url` (string, optional) ### ResponsesItemsItemsCalculated - `score` (double, optional) ### ResponsesItemsItemsDefinition Subset of a complete form definition to be included with a submission. - `fields` (list of ResponsesItemsItemsDefinitionFieldsItems, optional) ### ResponsesItemsItemsHidden ### ResponsesItemsItemsMetadata Metadata about a client's HTTP request. - `user_agent` (string, required) - `platform` (string, optional) — Derived from user agent - `referer` (string, optional) - `network_id` (string, optional) — Ip of the client ### ResponsesItemsItemsVariablesItems The required properties depend on the `type` value. - `key` (string, required) - `type` (enum, required) - Allowed values: `text`, `number`, `text`, `number` - `number` (double, optional) — Required for `number` type. - `text` (string, optional) — Required for `text` type. ### ResponsesItemsItemsAnswersItemsChoice Represents single choice answers for dropdown-like fields. - `label` (string, optional) - `other` (string, optional) ### ResponsesItemsItemsAnswersItemsChoices Represents multiple choice answers. - `ids` (list of string, optional) — ids of the different chosen choices - `labels` (list of string, optional) — labels of the different chosen choices - `other` (string, optional) — user provided value for the 'other' choice (if allowed by the field) - `refs` (list of string, optional) — refs of the different chosen choices ### ResponsesItemsItemsAnswersItemsField - `id` (string, required) — The unique id of the form field the answer refers to. - `ref` (string, required) — The reference for the question the answer relates to. Use the `ref` value to match answers with questions. The Responses payload only includes `ref` for the fields where you specified them when you created the form. - `type` (enum, required) — The field's type in the original form. - Allowed values: `short_text`, `long_text`, `email`, `website`, `dropdown`, `file_upload`, `date`, `multiple_choice`, `picture_choice`, `yes_no`, `legal`, `number`, `rating`, `opinion_scale`, `phone_number`, `payment`, `ranking`, `short_text`, `long_text`, `email`, `website`, `dropdown`, `file_upload`, `date`, `multiple_choice`, `picture_choice`, `yes_no`, `legal`, `number`, `rating`, `opinion_scale`, `phone_number`, `payment`, `ranking`, `short_text`, `long_text`, `email`, `website`, `dropdown`, `file_upload`, `date`, `multiple_choice`, `picture_choice`, `yes_no`, `legal`, `number`, `rating`, `opinion_scale`, `phone_number`, `payment`, `ranking`, `short_text`, `long_text`, `email`, `website`, `dropdown`, `file_upload`, `date`, `multiple_choice`, `picture_choice`, `yes_no`, `legal`, `number`, `rating`, `opinion_scale`, `phone_number`, `payment`, `ranking` - `title` (string, optional) — The form field's title which the answer is related to. ### ResponsesItemsItemsAnswersItemsPayment - `amount` (string, optional) — amount paid - `completed` (boolean, optional) — whether the payment was completed or not - `last4` (string, optional) — last 4 digits of the credit card - `name` (string, optional) — cardholder of the payment ### ResponsesItemsItemsDefinitionFieldsItems Subset of a complete field definition to be included with a submission. - `description` (string, optional) - `id` (string, optional) - `title` (string, optional) - `type` (string, optional) ## Examples **Response** ```json { "total_items": 1.1, "page_count": 1.1, "items": [ { "answers": [ { "type": "choice", "boolean": true, "choice": { "label": "string", "other": "string" }, "choices": { "ids": [ "string" ], "labels": [ "string" ], "other": "string", "refs": [ "string" ] }, "date": "2024-01-15T09:30:00Z", "email": "string", "field": { "id": "string", "ref": "string", "type": "short_text", "title": "string" }, "file_url": "string", "number": 1.1, "payment": { "amount": "string", "completed": true, "last4": "string", "name": "string" }, "text": "string", "url": "string" } ], "calculated": { "score": 1.1 }, "definition": { "fields": [ { "description": "string", "id": "string", "title": "string", "type": "string" } ] }, "hidden": {}, "landed_at": "string", "landing_id": "string", "metadata": { "user_agent": "string", "platform": "string", "referer": "string", "network_id": "string" }, "response_id": "string", "submitted_at": "string", "variables": [ { "key": "string", "type": "text", "number": 1.1, "text": "string" } ] } ] } ``` **SDK Code** ```python import requests url = "https://api.typeform.com/forms/:form_id/responses" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.typeform.com/forms/:form_id/responses'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.typeform.com/forms/:form_id/responses" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.typeform.com/forms/:form_id/responses") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.typeform.com/forms/:form_id/responses") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.typeform.com/forms/:form_id/responses', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.typeform.com/forms/:form_id/responses"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.typeform.com/forms/:form_id/responses")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```