Guides

Reference

Guides

Migrate from the Data API to the Responses API

NOTE: The Data API is now deprecated. Please use the information in this guide to migrate to the Responses API.

We've replaced our Data API with our Responses API. Both let you retrieve your typeform's results programmatically, but there are some important differences to understand when you're migrating from the Data API to the Responses API.

This guide describes what's changed and what's the same to help make your shift to the Responses API as smooth as possible. You can also learn more about the Responses API and review Responses endpoint documentation.

If you prefer an automatic and immediate approach to retrieving your typeform responses, check out our Webhooks API. With Webhooks, you can send every typeform submission straight to any URL or compatible web application — no requests needed.

Note that with the Responses API, you won't include authentication details as part of the URL like you did with the Data API. Instead, you authenticate by passing an access token in the Authorization header of your requests.

The Responses API still includes query parameters you can use to filter your results. Check out the Retrieve responses endpoint documentation for details.

Payloads

The payloads for the Data API and Responses API are different.

In terms of structure, the Data API payload followed this order:

HTTP status for the form

A stats object that lists stats like the number of responses and number of completed forms

An array of the form's questions

An array of the answers for each response, including information like the landing and submission time, the device and browser the respondent used, the typeform's URL, and the respondent's network ID in addition to the answers themselves

Response data about the number of responses your request retrieved and the number of pages in the payload

A general data object for each response in the payload that includes information like the landing and submission time, the device and browser the respondent used, the typeform's URL, and the respondent's network ID

An answers array for each response, which lists the question, question type, accepted answer type, and the answer itself

Data API 'id' vs. Responses API 'field'

In the Data API, each question had an id to use for matching answers with the right questions. In the Responses API, this is the field.

Here's an at-a-glance summary of how the id in the Data API translates to the field in the Responses API for each question type:

Question Type

Data API

Responses API

date

id : date_xxxxxx

field : { type : 'date' , id : xxxxxx }

dropdown

id : dropdown_xxxxxx

field : { type : 'dropdown' , id : xxxxxx }

email

id : email_xxxxxx

field : { type : 'email' , id : xxxxxx }

file_upload

id : fileupload_xxxxxx

field : { type : 'file_upload' , id : xxxxxx }

group

id : group_xxxxxx

Not used in Responses API

legal

id : terms_xxxxxx

field : { type : 'legal' , id : xxxxxx }

long_text

id : textarea_xxxxxx

field : { type : 'long_text' , id : xxxxxx }

multiple_choice

id : list_xxxxxx_choice

field : { type : 'multiple_choice' , id : xxxxxx }

number

id : number_xxxxxx

field : { type : 'number' , id : xxxxxx }

opinion_scale

id : opinionscale_xxxxxx

field : { type : 'opinion_scale' , id : xxxxxx }

payment

id : payment_xxxxxx_price

field : { type : 'payment' , id : xxxxxx },

id : payment_xxxxxx_last4

payment: { name: "x", last4: "x", amount: "x" }

id : payment_xxxxxx_name

id : payment_xxxxxx_success

picture_choice

id : listimage_xxxxxx_choice

field : { type : 'picture_choice' , id : xxxxxx }

rating

id : rating_xxxxxx

field : { type : 'rating' , id : xxxxxx }

short_text

id : textfield_xxxxxx

field : { type : 'short_text' , id : xxxxxx }

statement

id : statement_xxxxxx

Not used in Responses API

website

id : website_xxxxxx

field : { type : 'website' , id : xxxxxx }

yes_no

id : yesno_xxxxxx

field : { type : 'yes_no' , id : xxxxxx }

Retrieving a list of all your typeforms

With the Data API, you sent a request to https://api.typeform.com/v1/forms?key={your_api_key} to get a list of all your typeforms and their unique identifiers. Now, you use the Retrieve forms in our Create API to get this information — it's not part of the Responses API.

Filtering parameters

The Responses API includes parameters you can add to the request URL to filter your results, although they are a bit different from the paramaters that were available in the Data API.

Sorting options

The Data API included sorting options for listing your responses in order based on completion, landing date, and date of submission.

In the Responses API, responses are automatically sorted by the date they were submitted, from newest to oldest. We plan to add more options for sort order soon.

What's next?

Don't forget to check out our Webhooks API for a different approach to retrieving your typeform responses. And when you're ready to develop a new typeform or update an existing typeform, try our Create API.