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.

curl -u API_KEY: -H "Accept: application/vnd.unbounce.api.v0.4+json" -X GET https://api.unbounce.com

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

Managing API Keys

We have enabled API Access to all of our customers on an Essential, Premium or Enterprise plan. Now you can create one or more API Keys within the app (and yes, auto-serve OAuth is coming soon).

  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

1. Test your new API Key by running
curl -u API_KEY: -H "Accept: application/vnd.unbounce.api.v0.4+json" -X GET https://api.unbounce.com/accounts

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.

Using OAuth

Register a new OAuth Application

We're still working on providing self-service for OAuth applications, but in the mean time, you can register one by filling this form.

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
  1. The Unbounce API OAuth server will return a temporary code to the callback URL you previously registered for your application.

  2. Your application needs to validate this code before receiving an access token. The URL you need to validate with is:

https://api.unbounce.com/oauth/token
  1. 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

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.


HTTP Response Codes
  • 200

    OK
    Successful request.
  • 400

    Bad Request
    The request could not be understood, possible syntax malformation.
  • 401

    Unauthorized Request
    The request requires user authentication. API Key or Access Token is missing.
  • 403

    Forbidden Access
    The API Key is forbidden to access the resource, or the Access Token is bad or has expired.
  • 404

    Not Found
    The server has not found anything matching the request-uri.
  • 409

    Version Conflict
    The request could not be completed due to a conflict with the current state of the resource.
  • 429

    Too many requests
    Too many request in a given amount of time.
  • 500

    Server Error
    Something went wrong on Unbounce's end.

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

{ "accountId" : 52 } => { "account_id" : 52 }
  • Using string in favor of integer for ID fields
{ "accountId" : 52 } => { "account_id" : "52" }
  • page_uuid is renamed to page_id
{ "page_uuid" : "abc-123" } => { "page_id" : "abc-123" }
  • Omit optional properties instead of nullifying them
{ "page_id" : "abc-123", "created_at" : null } => { "page_id" : "abc-123" }
  • Replaced date format for consistency with query parameters
{ “created_at” : “2015-12-16T00:34:47+00:00” } => { “created_at” : “2015-12-16T00:34:47.000Z” }
  • Removed internal_page_id field from page tests

  • Removed uuid field in sub_accounts

  • Removed options from account and sub_account