Get Started with the NextRoll API

The NextRoll API is divided into several services, each with its own focus. Every API uses a common base URL and the authentication method. API parameters and responses can vary with each service, however we try to use consistent terminology across services. If you have any questions, you can contact the API team.

For a high-level overview of the object structure, see Get to know NextRoll.

Register as a Developer

To make API calls, you’ll need to register as developer and create an application:

  1. Create a developer account

  2. Create an application

It is recommended that you create an application for production and one for testing. This allows you to have a separate OAuth 2.0 redirect URI for each of your development environments.

The default quota is 100 API requests per service per day. If you think you need your limit increased, send us a message.

Note

Be sure to give your application a meaningful name. Users will see the name on the OAuth consent page and it helps us when reviewing usage for quota increases.

Note

Once you’ve registered your application, you’ll see both a consumer key and secret. You’ll only use the consumer key when making API calls using Personal Access Tokens. You’ll use both key and secret when authenticating with OAuth 2.0.

Base URL

The base URL for all API calls is:

https://services.adroll.com

HTTPS is the only supported protocol.

Authentication

OAuth 2.0

All API calls are authenticated using OAuth 2.0. For information on how to use OAuth 2.0 see Get Started with OAuth 2.0.

Personal Access Tokens

Personal Access Tokens (PAT) are a simple way for developers to make API calls. Developers use them in simple API integrations and scripts where OAuth is not practical. If you’re building an application where you need to ask your users for their Personal Access Token, you should instead use OAuth.

To get started, first visit the your settings page in the dashboard. From this page, you’ll be able to create and revoke Personal Access Tokens.

To make a request using a Personal Access Token, you need to include two things: your Personal Access Token and your application’s client ID. The Personal Access Token identifies the AdRoll or RollWorks user. The client ID identifies the application making the API call.

The Personal Access Token is sent via the Authorization header with the Token scheme. For example: Authorization: Token MYTOKEN

You’ll also need to pass your application’s client ID in the apikey query parameter. The apikey parameter is always sent in the URL’s query string, regardless of the HTTP method used. The apikey parameter should not be included in the body of the request for POST, PUT, or PATCH calls.

A complete request would look something like:

curl --header 'Authorization: Token MYTOKEN' \
    'https://services.adroll.com/api/v1/organization/get_advertisables?apikey=MYAPIKEY'

Your First API Call

The Advertisable is commonly used object in user accounts. Since the Advertisable EID will be used for most API calls, it is recommended to retrieve the Advertisable EID as your first API call.

Using cURL:

curl -H 'Authorization: Token YOUR_TOKEN' \
    'https://services.adroll.com/api/v1/organization/get_advertisables?apikey=MYAPIKEY'

Using the Requests library in Python:

r = requests.get(
    'https://services.adroll.com/api/v1/organization/get_advertisables?apikey=MYAPIKEY',
    headers={
        'Authorization': 'Token MY_TOKEN'
    }
)

Using PHP:

<?php
// create curl resource
$ch = curl_init();

// set url
$url = "https://services.adroll.com/api/v1/organization/get_advertisables?apikey=MYAPIKEY";
curl_setopt($ch, CURLOPT_URL, $url);

// return the transfer as a string
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Set credentials
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Token MY_TOKEN'
));

// $output contains the output string
$output = curl_exec($ch);

Using node-fetch library Node.JS:

const fetch = require("node-fetch");

const apiKey = "API_KEY";
const myToken = "MY_TOKEN";
const endpoint = "https://services.adroll.com/api/v1/organization/get_advertisables?apikey=" + apiKey;

fetch(endpoint, {
    headers: {
        "Content-Type": "application/json",
        Authorization: "Token " + myToken,
    },
})
.then(async (res) => {
    const data = await res.json();
    if (res.ok) {
        console.log(data);
    } else {
        console.error(data);
    }
})
.catch(console.error);