Responses API walkthroughs

With the Responses API, you can retrieve your typeform’s results on-demand, manually or programmatically, without setting up a webhook or third-party integration. Responses also offers powerful query parameters you can use to filter the data you retrieve. Let's walk through the basics.

NOTE: These walkthroughs assume that you already have your Typeform access token and know how to pass it in the Authorization header of your request. If you need an access token or don't know how to pass it in the Authorization header, head to the Get started section first.

If you want to retrieve responses for your typeform, it's a straightforward process: send a GET https://api.typeform.com/forms/{form_id}/responses.

By default you will receive 25 responses. In order to change the number of responses, use the page_size parameter. Max. value is 1000.

If you want to iterate through responses, use the since/until or before/after query parameters. For more information see retrieve responses documentation

Suppose you expect thousands of responses to your typeform, but always fewer than 1000 per day. To keep your Responses API requests manageable, you decide to retrieve your typeform's data once each day. In other words, you'll retrieve yesterday's data today, todays's data tomorrow, and so on. Because you don't want to retrieve every response to your typeform, you'll use the since and until query parameters to narrow the scope of your request and limit the API response by date.

NOTE: Other query parameters for the Responses API include page_size, which lets you specify the number of results to retrieve (up to 1000), and query, which lets you limit responses to those that contain a certain term. For a complete list of query parameters for the Responses API, see the reference documentation.

Use the since and until query parameters to retrieve a date range

Let's assume today is July 10, 2017, and you're going to retrieve the the previous day's data. Here's the walkthrough:

1. You'll still use the GET https://api.typeform.com/forms/{form_id}/responses endpoint, but don't send your request yet!

2. Add the since query parameter to your request. The since parameter is a string that uses ISO 8601 format, Coordinated Universal Time (UTC), with "T" as a delimiter between the date and time. July 10, 2017 at 12:00 a.m. UTC is expressed as 2017-07-10T00:00:00. If you want to retrieve responses for yesterday, 2017-07-09, the value for your since query parameter would be 2017-07-09T00:00:00. This means your response will include typeform responses received since 12:00 a.m. UTC on July 9, 2017.

3. Add the until query parameter to your request. The until parameter is also string in the same format as the since parameter. The value for your until query parameter would be 2017-07-10T00:00:00. This means your response will include typeform responses received up until 12:00 a.m. UTC on July 10, 2017.

Here's what the cURL request looks like:

curl --request GET \
  --url 'https://api.typeform.com/forms/{form_id}/responses?since=2017-07-09T00%3A00%3A00&until=2017-07-10T00%3A00%3A00' \
  --header 'authorization: bearer {your_access_token}'

Now, you can send your request. The response will include only the responses that were submitted yesterday, July 9, 2017.

Use the before query parameter to paginate

Suppose one of your typeforms received hundreds of responses, and you want to page through them 25 at a time to keep things manageable. To do this, limit your Responses request using the token property and the before parameter. Here's the walkthrough:

1. Send a request to the GET https://api.typeform.com/forms/{form_id}/responses endpoint, but add the page_size query parameter and specify 25 responses: GET https://api.typeform.com/forms/{form_id}/responses?page_size=25. This retrieves the first 25 responses for your form.

2. Find the token property for the 25th response listed. Each response to your typeform starts with a general data object that includes the token.

3. Send another GET request with page_size=25 and add the before query parameter. The value for the before parameter should be the token value for the 25th response: GET https://api.typeform.com/forms/{form_id}/responses?page_size=25&before={token_value_25th_response}. This retrieves the next 25 responses for your form.

4. Continue to send requests using page_size=25 and before={token_value_25th_response} until you have retrieved all responses for your form. You will update the before value each time to match the token value for the 25th response in the previous set of responses.

NOTE: The after query parameter works just like the before parameter, except that it retrieves responses after the token value you specify. For example, the request GET https://api.typeform.com/forms/{form_id}/responses?page_size25&after={token_value_1000th_response} will retrieve responses 1001 to 1026 for your typeform.

You can develop your own web app that authenticates your Typeform logon and retrieves and displays the responses for your typeform at the click of a button. When you start your next Typeform campaign, you can reuse your app by updating your code with the new typeform's form_id.

We developed an example application to help you envision how your own app might work.

If you need your access token, check out our Get started section. If you have your token and you want to retrieve responses for an existing typeform, head to the Responses API reference documentation.

If you want to create a form, head to the Create API.