Create applications that integrate with Typeform's APIs

Typeform uses OAuth 2.0 to secure the endpoints for the Create, Responses, and Webhooks APIs. To use our APIs, you need to pass an access token in the Authorization header of your requests. Our Embed SDK doesn't require an access token.

If you're familiar with using OAuth 2.0 libraries and building apps that use OAuth 2.0 authentication, here's the information you need to get started:

For more details, read on!

You need to register your application in your Typeform account for it work with the Typeform OAuth 2.0 mechanism. When you register your app, you'll receive the client_id and client_secret for your application, which are used during the OAuth 2.0 process to generate an access token. Here's a diagram of Typeform's OAuth 2.0 flow to illustrate how it works:

Access tokens are long strings of random characters that look something like this: 943af478d3ff3d4d760020c11af102b79c440513.

NOTE: Anyone with the access token can read, update, and delete your app users' typeforms and data, so keep access and refresh tokens and client_id and client_secret codes safe! Also, don't commit to source control with access or refresh tokens, or your client_id or client_secret in your code — use a placeholder like CLIENT_ID (or CLIENT_SECRET) instead.

Let's walk through the steps to register your application and start working with Typeform's APIs. Here's the code for the example we're using to illustrate the steps.

1. Log in to your account at Typeform.
2. In the upper-left corner, click icon drop-down menu next to your organization name.
3. Under Organization section, click Developer Apps.
4. Click Register a new app.
5. In the App Name field, type the name for your new app.
6. In the App website field, type the complete URL for your app's homepage.
7. In the Redirect URI(s) field, type the complete callback URL for your app.
8. Click Register app.

After you save your app, the app's client_secret will be shown only once. Make sure you copy it and store it somewhere safe.

After that, you'll be able to see the client_id in the Developer Apps panel.

NOTE: If you didn't copy the client_secret, lost it, or suspect that it could be compromised, you can regenerate it. In the Edit app panel, click the Regenerate client secret button to generate a new one.

Now that you've created your app with Typeform, you can write the application itself. Your application will need to generate an access token (and possibly also a refresh token) to integrate with Typeform's APIs. This requires making authorization and authentication requests through your browser-based application.

The first request, GET https://api.typeform.com/oauth/authorize, confirms your client_id, prompts the user to grant the permissions your app requires, and returns a temporary authorization code. The second request, POST https://api.typeform.com/oauth/token, confirms your temporary authorization code and returns your access token.

Your application's https://api.typeform.com/oauth/authorize link, including parameters, might look like this:

https://api.typeform.com/oauth/authorize?state=xyz789&client_id={your_client_id}&redirect_uri=https://results-example.herokuapp.com/callback&scope={scope1}+{scope2}+{scope3}

This table describes each parameter:

Clicking the https://api.typeform.com/oauth/authorize link in your app should redirect to the Typeform login screen so users can log in to their Typeform accounts. Then, they'll see a consent screen that lists the scope of access and prompts them to grant or deny access to your app. Here's an example consent screen:

If the user grants access to your app, Typeform generates a temporary authorization code and redirects the browser to a URL that includes the code. Here's what that redirect URL might look like:

https://results-example.herokuapp.com/callback?code={temporary_authorization_code}&state=xyz789

Now that the application has a temporary authorization code, it can request an access token with POST https://api.typeform.com/oauth/token, sending the temporary authorization code, client_id, client_secret, and redirect_uri in the request body.

Your application's https://api.typeform.com/oauth/token request, including the body, might look like this:

curl --request POST \
  --url https://api.typeform.com/oauth/token \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code={temporary_authorization_code}' \
  --data-urlencode 'client_id={your_client_id}' \
  --data-urlencode 'client_secret={your_client_secret}' \
  --data-urlencode 'redirect_uri=https://results-example.herokuapp.com/callback'

This table describes each part of the request body:

Typeform then verifies all the data in the request body. If everything is OK, Typeform will send an access token to the application in a JSON response as per RFC 6749.

Applications that use the Create and Responses APIs must pass a valid access token in the Authorization header of every request.

NOTE: The default expiration period for the access tokens is 1 week.

After the token expires, your application won't be able to make requests with that token. You will need to get a new token either through the OAuth2 authentication process or by using the token refresh process in Step 4 (below).

If your application needs to call the Typeform APIs over longer periods of time without user involvement, your application can request a special refresh token during the first authentication call, then use this refresh token to obtain new access tokens without asking for user permission each time.

To receive a refresh token in the first place, your application must pass an extra offline scope during the authorization code request:

https://api.typeform.com/oauth/authorize?state=xyz789&client_id={your_client_id}&redirect_uri=https://results-example.herokuapp.com/callback&scope=offline+{scope1}+{scope2}+{scope3}

If the user agrees to grant your application the required permissions, in the authorization code response to the access token exchange request, your application will receive the access_token and an extra parameter called refresh_token. You can use the value of this refresh_token parameter to obtain a new access token at any time as per RFC 6749.

curl --request POST \
  --url https://api.typeform.com/oauth/token \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token={your_refresh_token}' \
  --data-urlencode 'client_id={your_client_id}' \
  --data-urlencode 'client_secret={your_client_secret}' \
  --data-urlencode 'scope={scope1} {scope2}'

This table describes each part of the request body:

The response for this request is nearly identical to the response for the authorization code to the access token exchange request. The only difference that this response will always include the refresh_token parameter, which will contain the newly generated refresh token.

NOTE: For security purposes, the refresh procedure will invalidate the old refresh token. Therefore, your application won't be able to use the old refresh token anymore. Instead, your application should use the newly generated refresh token returned in the response to this query.

Create your own applications that integrate with Typeform's APIs! If you're looking for inspiration, you can find out what other open-source developers are doing on our Community projects page.

You can also take a look at an explanation for a JSON response from our Responses API to see how they're structured. Or head straight to one of our APIs to learn more about how they work and available endpoints — they're listed on the left side of the page.

If you want to directly access Typeform's APIs (for example, using cURL or Postman), learn how to get a personal access token and start making requests.