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.
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.
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).
Log in to your Unbounce account and go to Manage Account
Click on API Access on the left sidebar menu
Create a new API Key
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.
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:
- Sub Accounts or Clients
- Page Groups
OAuth is a protocol that enables applications to act on behalf of their users.
Once you have registered your OAuth Application and have received your Client ID and Client Secret:
- Authorize your application
The Unbounce API OAuth server will return a temporary code to the callback URL you previously registered for your application.
Your application needs to validate this code before receiving an access token. The URL you need to validate with is:
- 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
OAuth tokens grant the same permissions that the user that is authenticating already has.
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.
Unbounce uses conventional HTTP response codes to indicate the success or failure of an API request.
HTTP Response Codes
400Bad RequestThe request could not be understood, possible syntax malformation.
401Unauthorized RequestThe request requires user authentication. API Key or Access Token is missing.
403Forbidden AccessThe API Key is forbidden to access the resource, or the Access Token is bad or has expired.
404Not FoundThe server has not found anything matching the request-uri.
409Version ConflictThe request could not be completed due to a conflict with the current state of the resource.
429Too many requestsToo many request in a given amount of time.
500Server ErrorSomething went wrong on Unbounce's end.
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"
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