Typeform.com Data API

Fetch your typeform’s results programmatically. The Data API provides a direct, machine-friendly way of accessing the data collected by your typeforms, so you can pull it into your own application on demand.

Unlike Webhooks, or integration with Zapier, which pushes your data to your own application as soon as your typeform is submitted, the Data API must be called each time you require your data. Each typeform’s data can be fetched up to two times per second.

Why is the Data API useful?

When you’re signed in to the Typeform.com platform, you can view your typeform’s responses in the results table and you can also export your results in .csv or .xls (Excel Spreadsheet) format, for example.

But if you regularly want to get your results data out of Typeform and into your own application elsewhere on the web, you don’t want to be doing it by hand each time; it’s better to write code that will do it for you.

This is what the Data API allows you to do. The Data API provides a way for your application to fetch results from Typeform by itself, as required, without having to sign in to the platform.

How to use the Data API

To use the Data API, you will need:

  • Your API key — this is unique and private to you.
  • The UID (unique identifier) of the typeform you want the results for.

What is my API key?

Your API key is a long string of random characters which is unique to you. It looks something like this: 943af478d3ff3d4d760020c11af102b79c440513

Instead of a login and password, your private API key is what we use to identify you and your requests, and make sure that only you can access your results. Whenever you send a request to the Data API, you send this key along with it so that we know it’s you!

How to find your API key

When you’re signed in to the Typeform.com admin panel, click on “My Account” (in the top right hand corner). Then at the bottom of the “My Account” page, you will find your API key as well as an option to regenerate a new API key, if you need to.

API Key [EN]

How to find your typeform’s UID

Each typeform you create has a Unique ID, and the easiest way to find it is to look at the typeform’s URL: the typeform’s UID is the code right at the end of the URL. So for example, in this case:

https://username.typeform.com/to/AcFQ3B   …  the UID is: AcFQ3B

Accessing Results / Making Requests

Once you’ve got the UID of the typeform and your API key, you’ve got everything you need to start making requests to the Data API, and start fetching your results.

The URL of your request takes the following format:

https://api.typeform.com/v1/form/[typeform_UID]?key=[your_API_key]
Substituting [typeform_UID] with the UID of your typeform and [your_API_key] with your API key

Here’s a full example:

https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd

This request will return all the results for the typeform with UID Ab12C3, as long as the API key is the right one!

HTTP status code summary

HTTP status code summary

Filtered calls not displaying as expected

Filtered calls not displaying properly

Filtering Results/Request Parameters

Ordered calls not displaying as expected

Now we can take a look at how to refine and order our search results by adding parameters to the URL of your API requests.

Filtering Options

You can add the following parameters to the request URL, in any combination, to filter your results:

  • completed: boolean (true or false)
    • Example:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&completed=true
    • Fetch only completed results (=true), or only not-completed results (=false).
    • Note: a not-complete result only contains data about, for example, the respondent’s device and location (as well as any hidden fields you’ve used). We do not store any results data from partially complete typeforms.
    • Both completed and not-completed result will be returned by default, if this parameter is not provided.
  • since: number (Unix time/Timestamp)
    • Example:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&since=1441703930
    • Fetch only the results after a specific date and time.
    • Responses are returned in order of oldest-to-newest.
  • until: number (Unix time/Timestamp)
    • Example:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&until=144170392930
    • Fetch only the results before a specific date and time.
    • Responses are returned in order of oldest-to-newest.
  • offset: number
    • Example:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&offset=20
    • Fetch all results except the first 20. i.e. Start listing results from result #21 onwards.
    • Especially useful for pagination.
  • limit: number
    • Example:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&offset=20&limit=20
    • Fetch only 20 results (starting from result #21 (&offset=20)).
    • Especially useful for pagination.
  • token: response token (string)
    • Example:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&token=31f62937ba8723aa2a6198331d2ef11d
    • Fetch a single result, identified by its token.

Ordering Options

You can add the following parameter to the request URL, in combination with any filter parameters (see above), to apply a specific order to your results:

?order_by=value

And value can be any one of the following:

  • completed
    • Example:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by=completed
    • Show not-completed results first (before completed results).
  • date_land
    • Example:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by=date_land
    • Order results by when the form was loaded (i.e. “landed on”) by the respondent.
    • Default order = date ascending (oldest-to-newest). This can be changed to descending if desired (see below for instructions).
  • date_submit
  • Example:
    https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by=date_submit
  • Order results by when the form was submitted by the respondent.
  • Default order = date ascending (oldest-to-newest). This can be changed to descending if desired (see below for instructions).

To sort by date_land or date_submit descending, you have to change the order_by= parameter slightly, to order_by[]= because it requires (an array of) 2 values.

  • date_land,desc
    • Example:
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by[]=date_land,desc
  • date_submit,desc
    • Example: 
      https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by[]=date_submit,desc
https://api.typeform.com/v1/form/Ab12C3?key=zx032900ff72f6d095b7cfba37522c00dfb8dfcd&order_by[]=completed&order_by[]=date_submit,desc

Example URL with Multiple Filters / Order

Imagine our typeform has the URL http://username.typeform.com/to/AbCd99. And we want to fetch only the last 10 completed responses.

  • We only want completed results, so we add the parameter completed=true.
  • The results need to be ordered by newest results first, so we add the parameter order_by[]=date_submit,desc.
  • We only want 10 results maximum, so we add the parameter limit=10.
  • And we need to add our private API key too so that Typeform knows it’s really us calling! Let’s say our API key is 1z2y3x4w5v6u7t8s9r10q11p12o13n14m15l

The final URL for our API request will look something like this:

https://api.typeform.com/v1/form/AbCd99?key=1z2y3x4w5v6u7t8s9r10q11p12o13n14m15l&completed=true&order_by[]=date_submit,desc&limit=10

Note: the parameters we’ve added don’t have to be in any particular order.

Fetching a List of All Your Typeforms

You can get a list of all your typeforms and their UIDs by making a request to the following URL, using your private API key:

https://api.typeform.com/v1/forms?key=YOUR_API_KEY

Example Payload

Here’s an example of the responses you get calling the Data API:

{
“http_status”:200,
“stats”:{
“responses”:{
“showing”:5,
“total”:5,
“completed”:2
}
},
“questions”:[
{
“id”:”textfield_37671344″,
“question”:”What is your name?”,
“field_id”:37671344
},
{
“id”:”date_37962697″,
“question”:”What date were you born?”,
“field_id”:37962697
},
{
“id”:”email_37962684″,
“question”:”What’s your email address?”,
“field_id”:37962684
},
{
“id”:”textarea_37671420″,
“question”:”Please tell us a little about yourself.”,
“field_id”:37671420
},
{
“id”:”website_37962927″,
“question”:”Please add your website URL:”,
“field_id”:37962927
},
{
“id”:”statement_37671505″,
“question”:”Thanks !”,
“field_id”:37671505
},
{
“id”:”yesno_37977952″,
“question”:”Are you a Game of Thrones fan?”,
“field_id”:37977952
},
{
“id”:”terms_37962909″,
“question”:”Please read and confirm you accept our terms and conditions:”,
“field_id”:37962909
},
{
“id”:”dropdown_37671567″,
“question”:”Who’s your favourite Game of Thrones character?”,
“field_id”:37671567
},
{
“id”:”listimage_37967229_choice”,
“question”:”Which of these characters annoys you the most?”,
“field_id”:37967229
},
{
“id”:”group_37977292″,
“question”:”Rate the deviousness of these Game of Thrones characters:”,
“field_id”:37977292
},
{
“id”:”rating_37977395″,
“question”:”Tyrion Lannister”,
“field_id”:37977395,
“group”:”group_37977292″
},
{
“id”:”rating_37977403″,
“question”:”Littlefinger”,
“field_id”:37977403,
“group”:”group_37977292″
},
{
“id”:”rating_37977401″,
“question”:”Walder Frey”,
“field_id”:37977401,
“group”:”group_37977292″
},
{
“id”:”rating_37977400″,
“question”:”Margaery Tyrell”,
“field_id”:37977400,
“group”:”group_37977292″
},
{
“id”:”list_37963973_choice”,
“question”:”Who is going to sit on the Iron Throne at the end of the series?”,
“field_id”:37963973
},
{
“id”:”list_37963973_other”,
“question”:”Who is going to sit on the Iron Throne at the end of the series?”,
“field_id”:37963973
},
{
“id”:”opinionscale_37979723″,
“question”:”How much better would the series be without the Dragons?”,
“field_id”:37979723
},
{
“id”:”fileupload_37980234″,
“question”:”Please upload a file here:”,
“field_id”:37980234
},
{
“id”:”number_37980157″,
“question”:”How many major characters do you think have died in Game of Thrones?”,
“field_id”:37980157
},
{
“id”:”payment_37962979_price”,
“question”:”The total price is: “,
“field_id”:37962979
},
{
“id”:”payment_37962979_last4″,
“question”:”The total price is: “,
“field_id”:37962979
},
{
“id”:”payment_37962979_name”,
“question”:”The total price is: “,
“field_id”:37962979
},
{
“id”:”payment_37962979_success”,
“question”:”The total price is: “,
“field_id”:37962979
}
],
“responses”:[
{
“completed”:”0″,
“token”:”bbf6b7a9eaf65804f94c05d4568fc62f”,
“metadata”:{
“browser”:”default”,
“platform”:”other”,
“date_land”:”2016-11-29 16:36:11″,
“date_submit”:”0000-00-00 00:00:00″,
“user_agent”:”Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.71 Safari\/537.36″,
“referer”:”https:\/\/sjudd.typeform.com\/to\/A8TcDI”,
“network_id”:”7d19966666″
},
“hidden”:[
],
“answers”:{
}
},
{
“completed”:”1″,
“token”:”c0d44787a6bc86de34adf81976a624fb”,
“metadata”:{
“browser”:”default”,
“platform”:”other”,
“date_land”:”2016-11-29 16:59:16″,
“date_submit”:”2016-11-29 16:59:51″,
“user_agent”:”Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.71 Safari\/537.36″,
“referer”:”https:\/\/sjudd.typeform.com\/to\/A8TcDI”,
“network_id”:”7d19966666″
},
“hidden”:[
],
“answers”:{
“textfield_37671344”:”https:\/\/ssl.solutions.six.se\/fsb.public\/site\/public\/fondtorg\/funddetail_bank.page?magic=(cc(idAGL)) “,
“textarea_37671420”:”https:\/\/ssl.solutions.six.se\/fsb.public\/site\/public\/fondtorg\/funddetail_bank.page?magic=(cc(idAGL)) “,
“dropdown_37671567″:”Dropdown 1”
}
},
{
“completed”:”1″,
“token”:”7bac73ad0818db745da00479c12de987″,
“metadata”:{
“browser”:”default”,
“platform”:”other”,
“date_land”:”2016-12-05 09:59:01″,
“date_submit”:”2016-12-05 10:01:31″,
“user_agent”:”Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.71 Safari\/537.36″,
“referer”:”https:\/\/sjudd.typeform.com\/to\/A8TcDI”,
“network_id”:”7d19966666″
},
“hidden”:[
],
“answers”:{
“textfield_37671344″:”Sean”,
“date_37962697″:”2000-01-01”,
“email_37962684″:”test@typeform.com”,
“textarea_37671420″:”Here’s some information about me!”,
“website_37962927″:”http:\/\/test.com”,
“yesno_37977952″:”1”,
“terms_37962909″:”1”,
“dropdown_37671567″:”Sandor Clegane”,
“listimage_37967229_choice”:”Jon Snow”,
“rating_37977395″:”10”,
“rating_37977403″:”10”,
“rating_37977401″:”9”,
“rating_37977400″:”9”,
“list_37963973_choice”:”Daenerys Targaryen”,
“opinionscale_37979723″:”6”,
“fileupload_37980234″:”https:\/\/api.typeform.com\/v0\/form\/A8TcDI\/fields\/37980234\/blob\/c82215948b78-Cersei.jpg?key=664527c4c8bf2c6be6484b813e23e4f8ae066666”,
“number_37980157″:”37”,
“payment_37962979_price”:”0″
}
},
{
“completed”:”0″,
“token”:”b86db5dc48f6d021ee751e8f68595063″,
“metadata”:{
“browser”:”default”,
“platform”:”other”,
“date_land”:”2016-12-05 10:01:38″,
“date_submit”:”0000-00-00 00:00:00″,
“user_agent”:”Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/54.0.2840.71 Safari\/537.36″,
“referer”:”https:\/\/sjudd.typeform.com\/to\/A8TcDI”,
“network_id”:”7d19966666″
},
“hidden”:[
],
“answers”:{
}
},
{
“completed”:”0″,
“token”:”5df20a5aebea4e0edfb4d2d8670b4a4b”,
“metadata”:{
“browser”:”default”,
“platform”:”other”,
“date_land”:”2016-12-05 10:13:40″
}
Was this article helpful?
Thanks!