Getting Started

A new version of the Unbounce API (Beta) is now ready to be used! We are opening it up slowly but we would love to hear what you’re ready to build and the plans that you have to better integrate Unbounce with other products.

Authorization

There are two ways to authorize your application: using OAuth 2.0 tokens or an API key. Here's how to determine which option to use:

• If the request requires authorization for an individual's private data, let's say you want to build an application that will retrieve a user's Unbounce account information on their behalf, then the application must provide an OAuth 2.0 token.
• If the request doesn't require authorization from other users, let's say you only want to retrieve the data for a single account, then you only require an API key.

API Keys

You can use HTTP Basic Auth to interact with our API via API keys. Use your Unbounce API Key as the username and nothing as the password.

All connections require encryption via SSL, so make sure you use the HTTPS protocol in your requests.

Generate an API Key

Request API Access through the API Request form. Once you have access, you can create one or more API Keys within the app.

1. Log in to your Unbounce account and go to Manage Account

2. Click on API Access on the left sidebar menu

3. Create a new API Key

Or alternatively, browse the API Console and use your API Key as the username, leaving the password field blank.

Permissions

API keys currently act like Unbounce account administrators, this means the API key allows the client application to view every resource that an administrator of your account can view:

• Accounts
• Sub Accounts or Clients
• Domains
• Page Groups
• Pages
• Leads
• Users

OAuth

OAuth is a protocol that enables applications to act on behalf of their users. We use JSON Web Tokens (JWT) as the access tokens, which are valid only for a short time.

Once the access token expires, you can use a refresh token to request a new access token.

Using OAuth

Once you have registered your OAuth Application and have received your Client ID and Client Secret:

1. Authorize your application

   https://api.unbounce.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=URL_ENCODED_CLIENT_REDIRECT_URI

2. The Unbounce API OAuth server will return a temporary authorization code to the callback URL you previously registered for your application.
   
   Keep note of this authorization code, as you’ll be needing it in the coming steps.

3. Be sure that your application validates this authorization code to receive an access token. See below for the URL you need to send the POST request to, for the validation:

   https://api.unbounce.com/oauth/token
   The request will need to contain the following parameters:
   grant_type=authorization_code client_id=CLIENT_ID client_secret=CLIENT_SECRET code=AUTHORIZATION_CODE redirect_uri=CLIENT_REDIRECT_URI
   The response will contain the access token, expiration period and a refresh token:
   {   "access_token":"OAUTH_ACCESS_TOKEN",   "token_type":"bearer",   "expires_in":600,   "refresh_token":"OAUTH_REFRESH_TOKEN",   "scope":"full",   "created_at":1646256888 }
   Note: Currently only (default) scope: "full" is supported. Which provides access based on the user's credentials.

4. Now you can make requests to the server using your access token:

   curl -X GET -H "Accept: application/vnd.unbounce.api.v0.4+json" -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" https://api.unbounce.com/accounts

Refreshing an OAuth Access Token

To obtain a new access token for the user, the application will need to use the refresh token.

A new refresh token will also be issued at this time as well.

1. To start, send a POST request to the following URL:

   https://api.unbounce.com/oauth/token
   Doing so causes your application to request a new access token.
   
   The request will need to contain the following parameters:
   grant_type=refresh_token client_id=CLIENT_ID client_secret=CLIENT_SECRET refresh_token=OAUTH_REFRESH_TOKEN redirect_uri=CLIENT_REDIRECT_URI
   The response will contain the new access token, expiration period and a refresh token:
   {   "access_token":"OAUTH_ACCESS_TOKEN",   "token_type":"bearer",   "expires_in":600,   "refresh_token":"OAUTH_REFRESH_TOKEN",   "scope":"full",   "created_at":1646256888 }

2. Now you can continue making requests to the server with the new access token:

   curl -X GET -H "Accept: application/vnd.unbounce.api.v0.4+json" -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" https://api.unbounce.com/accounts

Permissions

OAuth tokens grant the same permissions that the user that is authenticating already has.

Rate Limiting

To make the API fast for everybody, we have a rate limit of 500 requests per minute per user account and IP address. If you get a status code 429 on your response, it means that you have exceeded this rate limit.

Errors

Unbounce uses conventional HTTP response codes to indicate the success or failure of an API request.

Versions

0.4

This is the latest version of our API. Optionally, you can pass in the explicit version of the API in the request header:

-H "Accept: application/vnd.unbounce.api.v0.4+json"

0.3

As of May 2018, the 0.3 version of our API is no longer accessible. If you had previously used this legacy version, you need to update your code to access the current version. Please find a reference of the changes below.

Changes between 0.3 and 0.4

• Removed the endpoint to list all leads for a given sub-account (as of May 2018)

• Snake case property names

• Using string in favor of integer for ID fields

• page_uuid is renamed to page_id

• Omit optional properties instead of nullifying them

• Replaced date format for consistency with query parameters

• Removed internal_page_id field from page tests

• Removed uuid field in sub_accounts

• Removed options from account and sub_account