Meet our introductory guide to the Native Advertising world >> Get your free download now

Connecting to the Taboola API Guide - Using Python and Jupyter Notebook

The Taboola Backstage API is a treasure trove for an advertiser who started to realize the limitation with the interface. All that is needed to work with it is a little bit of python knowledge or just a willingness to learn. Regardless if you just want to collect reporting data, make bulk campaign changes to bids and budgets or see if your creatives finally got approved. The Taboola API helps you do this much more efficiently.


How to connect to the Taboola API for advertisers using python

This is the first in our series of how to leverage the reporting and campaign management APIs of Native Ad Networks. Keep checking back for more relevant guides and let us know if there’s something specific you’d like us to cover.

All the Taboola API documentation can be found here, more specifically for the authentication here. Although the docs are well structured the trickiest thing is often, with few good resources to help, to get started and connected to the API. So in this guide we’ll go through, step by step, how to connect to the API and authenticate your requests. A prerequisite for whatever you would ever want to use the API for.

Python 3 and Jupyter Notebook is used in this guide. Don’t worry if you have no previous experience of either. It is not needed to follow. We do however assume that both are already installed on your computer. If not, this is an excellent guide on how to install python and jupyter notebook for windows and mac. Any other set up or IDE (program for writing and running code) for Python should work equally well.

Let’s get started!

Firsts things first, access to the API

In order to be able to connect to the Taboola Backstage API and access your advertiser account, you need a Client ID. If you’re not familiar with the term, you don’t really need to be. The client ID and client secret should be given to you by your Taboola account manager. Ask them about access to the API and they should send these over to you.

With your Client ID and Client Secret in hand, and saved somewhere so you won’t lose it, we are ready to move on.

The Taboola API Authentication Process

With every request made to the Taboola API you need to include a personal password for the API, called access token. This can be compared to you being logged in when directly using the website. So to get the Access Token you need to do the equivalent of logging in, this is the authentication process.

There are 4 different options for how to do the through the authentication process, described in detail in the Taboola API docs. We will not get into each one of them. Enough for now is to know that they’re appropriate for different kinds of uses.

The first option, and the one we will use, is based on using the client credentials. These are the client ID and client secret that you got in the previous step. With your development environment (Jupyter notebook or other) booted up. Let’s start the authentication process.

Joinative's native advertising e-book cover

Calling the Taboola API Server using Python

We need two Python libraries for connecting to and making sense out of the response from the Taboola API. These are called requests and json. Start by importing them using the code below:

import requests
import json

Let’s just run this first to make sure the packages are already installed. Do this by either on Windows hold “shift” and click on “enter”. See screenshot below. If you’re not getting any error message this step worked.


Import python packeges for taboola api connection

Now we need to give the Taboola API url and define the client credentials in the code.

The base for the Taboola Backstage API url is always https://backstage.taboola.com/ and we will make a request the specific /backstage/oath/token resource.

Below you can see the variables added and stored into a Python dictionary called payload. This is the data that gets sent to the Taboola API when we are making the request. The request we are making is a POST request, using the requests library that we imported in the beginning.

url = 'https://backstage.taboola.com'
client_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
client_secret = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
payload = {
  'client_id': client_id,
  'client_secret': client_secret,
  'grant_type': 'client_credentials'
}
response = requests.post(url + '/backstage/oauth/token', data=payload)
response.ok
response.json()

This produces the following output:


Import python packeges for taboola api connection

“In [5]” is checking whether the request was successful, returning True if it’s 200 status code (working as expected) or False if something went wrong in the request.

If the call was successful, as this one was, the response from Taboola will be JSON-formatted and contain the access token. The Taboola API access token expires after 12 hours. After which you would need to make another request to the /oauth/token url to get a new access token.

Now make sure to save the access token to a variable so that use can use it for making other requests to the API.

This is done using the following code:

access_token = response.json()['access_token']

Test the Taboola API Key

You have now successfully authenticated and have the Taboola API key (access token) needed to collect reporting data and make campaign changes through the API.

Let’s just quickly test the Access Token in a request to confirm that it’s working.

Use the code below to see which Advertiser account you have access to:

headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(url + '/backstage/api/1.0/users/current/allowed-accounts/', headers=headers)
response.ok
response.json()

This should return True when checking response.ok and show the accounts connected to your user when checking the JSON-formatted response from Taboola. See output below


Import python packeges for taboola api connection

Next Steps - The Taboola API Unlocked

With the access token and authentication under control you can now really start exploring the Taboola Backstage API. Automate boring tasks, collect data differently than you effectively would be able to do through the interface or build a stop all campaigns button. The possibilities are not endless but there are plenty of interesting options to keep you busy for a long time. Check out the Taboola API Documentation and have fun!

Thanks for reading through the accessing the Taboola API Python guide. We will keep releasing similar guides for other native advertising platforms and look closer into specific use cases for their APIs. Follow us on Linkedin for the latest updates and let us know if there’s something you’d like us to focus on!

If you’re looking for better ways of optimizing, managing and keeping track of your Native campaigns. Check out the Joinative Native Ads Management Platform. We integrate with all the largest networks and offer reporting and optimization features not available in the platforms.