Get hands-on with practice requests

This section complements the details about how Typeform's APIs work in Get started with a few practice requests to give you a hands-on perspective.

If you're looking for API-specific documentation and endpoints, choose an API from the left menu. Alternatively, you can create an application to access and integrate with our APIs.

To make these practice requests, you need a Typeform account and your personal access token, which you'll pass in the Authorization header in your request. If you've already got those, great! Let's get started.

For your first request, let's retrieve your Typeform alias, email address, and language with GET https://api.typeform.com/me.

Here's what you need for this request:

• An access token for the API (either your personal access token or an OAuth token granted to an application)
• The HTTP method
• The request URL

NOTE: If you're working with an OAuth token, make sure it has accounts:read scope.

This access token tells the API which account to retrieve user information from. You'll pass the access token in an Authorization header.

Your HTTP method for this request is GET.

The base URL for making a request is:

https://api.typeform.com/

or if your account is configured to store responses in the EU Data Center:

https://api.eu.typeform.com/

Combine the base with the /me endpoint to create the request URL:

https://api.typeform.com/me

Here's what this request looks like in cURL:

curl --request GET \
  --url https://api.typeform.com/me \
  --header 'Authorization: Bearer {your_access_token}'

And here's what this request looks like if you're using the Postman app:

NOTE: Whether you try it in cURL or Postman, make sure to replace {your_access_token} with your own access token.

Press Return to send your cURL request or Send to send your Postman request. The response will list your Typeform alias, email address, and language, in JSON format, like this:

{
  "alias": "Batman",
  "email": "bruce@wayne.com",
  "language": "en"
}

For this example, we'll make a request for a list of all of the responses for one of your typeforms: GET https://api.typeform.com/forms/{form_id}/responses. This endpoint is part of the Responses API.

NOTE: If you don't have a typeform with at least one response, try the request in Step 2b below.

Here's what you need for this request: your access token, the HTTP method, the request URL, and the form_id for your typeform.

Your access token is how the API knows which account to retrieve from. You'll pass your access token in an Authorization header.

Your HTTP method for this request is GET.

The base URL for making a request is:

https://api.typeform.com/

or if your account is configured to store responses in the EU Data Center:

https://api.eu.typeform.com/

When you combine the base with this endpoint, it looks like this:

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

That's your request URL.

The form_id is the unique ID for your typeform. You can find the form_id in your typeform's URL (for example, in https://mysite.typeform.com/to/u6nXL7, the form_id is u6nXL7.

Here's what this request looks like in cURL:

curl --request GET \
  --url https://api.typeform.com/forms/{form_id}/responses \
  --header 'Authorization: Bearer {your_access_token}'

And here's what this request looks like if you're using the Postman app:

NOTE: Whether you try it in cURL or Postman, don't forget to replace {your_access_token} with your own access token and {form_id} with the unique ID for your typeform.

Press Return to send your cURL request or Send to send your Postman request. The response will be a list of the responses received so far for your form, in JSON format.

You can paste your response into a tool like JSON Formatter and Validator if you want to see it in neatly formatted JSON.

Congratulations on making your first request! Head to Step 2 below to try another one. If you'd rather dig into one of our APIs or the Embed SDK, check out our documentation (it's listed in the main menu on the left).

NOTE: If you got an error in response to your request, check your access token, HTTP method, and request URL to confirm they're all correct. If those basics are correct, review our Troubleshooting and errors page to see if you can resolve the problem.

You can also check our Status page to confirm everything's up and running.

If your request is correct and we aren't having a status interruption, please let us know.

Let's make a request for a list of all of the themes that are in your account: GET https://api.typeform.com/themes. This endpoint is part of the Create API.

NOTE: Every Typeform account includes default themes, so you already have some themes in your account — even if you're a brand new to using Typeform.

Here's what you need for this request: your access token, the HTTP method, and the request URL.

Your access token is how the API knows which account to retrieve the themes from. You'll pass your access token in an Authorization header.

Your HTTP method for this request is GET.

The base URL for making a request is:

https://api.typeform.com/

or if your account is configured to store responses in the EU Data Center:

https://api.eu.typeform.com/

When you combine the base with this endpoint, it looks like this:

https://api.typeform.com/themes

That's your request URL.

Here's what this request looks like in cURL:

curl --request GET \
  --url https://api.typeform.com/themes \
  --header 'Authorization: Bearer {your_access_token}'

NOTE: Don't forget to replace {your_access_token} with your own access token.

Press Return to send your cURL request. The response will be a list of data about all of the themes in your account, in JSON format.

Here's what the response looks like in cURL:

You can paste your response into a tool like JSON Formatter and Validator if you want to see it in neatly formatted JSON.

With any luck, you've made your first request! Keep scrolling to Step 2 below to try another one. If you'd rather dig into one of our APIs or developer tools, check out our documentation (it's listed in the main menu on the left).

NOTE: If you got an error in response to your request, check your access token, HTTP method, and request URL to confirm they're all correct. If those basics are correct, review our Troubleshooting and errors page to see if you can resolve the problem.

You can also check our Status page to confirm everything's up and running.

If your request is correct and we aren't having a status interruption, please let us know.

If you want a little more practice, you're in the right place! Let's add query parameters to a request.

At the end of the response to a GET https://api.typeform.com/themes request, you'll see text like this:

"total_items": 43,
"page_count": 5

total_items is the total number of themes in your account. page_count is the number of pages in the response. In this example, there are 43 themes listed on 5 pages. You'll see different numbers if your Typeform account has more or fewer themes.

Our first request used the default parameters, so our response lists page 1, with the first 10 themes in your Typeform account. But how do you see page 2? And what if you want to see 20 themes per page instead of 10? You can do either (or both) by adding query parameters to your request URL.

The query parameters to use are page_size and page. page_size lets you specify how many themes to list per page, and page lists which page of the JSON response you want to see.

NOTE: In this request, the Authorization header and HTTP method stay the same. Only the request URL changes.

To retrieve the second page of results, with 20 themes listed per page, we'll add ?page_size=20&page=2 onto the end of the request URL like this:

http://api.typeform.com/themes?page_size=20&page=2

Here's what this request looks like in cURL:

curl --request GET \
  --url https://api.typeform.com/themes?page_size=20&page=2 \
  --header 'Authorization: Bearer {your_access_token}'

NOTE: Don't forget to replace {your_access_token} with your own access token.

Now, at the end of your response, you'll see the same number of responses (total_items), but you'll probably see a different number of pages (more responses listed per page means fewer pages).

"total_items": 43,
"page_count": 3

What happens if you change page_size to 40? What if you remove &page={x} from the request URL?

HINT: The maximum value for page_size is 1000, so you can see up to 1000 results per page of your response. Query parameters are optional, so if you remove &page={x}, you'll just see the first page of the results.

You can change the values for page_size and page in the request URL to change the number of themes listed on each page and the page displayed in the response. For some API endpoints, we offer even more query parameters you can use to refine your requests! For example, you can use query parameters to limit Responses results by date and filter to include only results for a specific question.

Check out the documentation for the API you're interested in — click the API name in the main menu to your left. You'll find overviews, walkthroughs, reference documentation, and more!

You can also find out what other open-source developers are doing on our Community projects page.