AdRoll CRUD API Usage

REST Semantics

The AdRoll API is RESTful. The API is made up of a number of services, and each service has the four standard CRUD functions: Create, Get, Edit, and Deactivate. The four HTTP verbs map to these functions in the following manner:

Verb AdRoll service function
PUT create
GET get
POST edit
DELETE deactivate

When using PUT or POST, parameters can be passed in the body of the request or in the URL query.

To pass parameters in the body of the request, use either application/x-www-form-urlencoded or multipart/form-data MIME types.

For PUT and POST requests you can also place parameters in the URL query:

PUT https://api.adroll.com/v1/ad?name=My+Ad&eid=XJCACTZQ2RHKRHU34YPFXQ

POST https://api.adroll.com/v1/ad/create?name=My+Ad&eid=XJCACTZQ2RHKRHU34YPFXQ

Request Headers

Please set the HTTP Accept header to ‘application/json’.

Response Values

When all is peachy, you’ll get a 200 OK HTTP response code and JSON with a results field that contains the function’s return value.

GET https://api.adroll.com/v1/ad?eid=XJCACTZQ2RHKRHU34YPFXQ
//Server says
200 OK

//JSON Response
{
    'results': {
        'ad': 'XJCACTZQ2RHKRHU34YPFXQ',
        ...
    }
}

Errors

In the event of an error, the API will return an appropriate HTTP response code and an errors field in place of the results field. The API’s HTTP response codes are unsurprising:

HTTP Response Code What Happened
200 Good to go
400 Validation error or missing input
401/403 You do not have access
404 We couldn’t find the object
405 HTTP method not allowed
500 You broke our service

The response’s errors field will be a list of error objects. Each error object will have a message field and either a code field or a field field. Occasionally, an error object will have both a code field and a field field, but this is rare. Field errors are retured in response to an error with one of the input fields, and errors without a field field are more generic errors.

In the case of a 405 response code, the allowed HTTP methods are listed as a comma-separated list in the Allow header of the response.

Let’s see what a grand failure looks like. What if we wanted to create an ad but didn’t specify any parameters except for an uploaded text file? We would have validation (field) errors and errors with a code field.

PUT https://api.adroll.com/v1/ad
//Server says
400 Bad Request

//JSON Response
{
    'errors': [{
        message: 'No Advertisable found',
        field: 'name',
        code: 16
    },{
        message: 'Please enter a name for your ad',
        field: 'name'
    },{
        message: 'Please enter a destination url',
        field: 'destination_url'
    },{
        message: 'File is an invalid image',
        field: 'ad_file',
        code: 1
    }]
}

The code field is an enum with the following values:

code value What it means
1 INVALID
2 MISMATCH
4 NO_DEFAULT
8 FAIL
16 NOT_FOUND
32 UNSET
64 INCOMPLETE
128 EXTERNAL
256 DUPLICATE
512 FORBIDDEN

Data Types

Throughout this documentation, we will be referring to a number of data types.

Data Type Description Example
String A string “My cat’s breath smells like cat food.”
Integer An integer 42
Float A real number 123.127
Boolean true or false true
List As input this means a comma-separated list of values in string form. This is often a list of object (e.g. Campaign) EIDs. As output from a service’s method, List will mean a JSON list. WPCWFT43KVFN3JKKZD2EYO,JXZWV4IW4RDALBFJIE3UPL
Binary A binary stream, like a file. 1010100101011110101010101010010
DateTime A date string in ISO 8601 format, with or without the time. 2009-03-23 19:00

Statuses

Campaign and ad objects have a status attribute.

These statuses may have different meanings depending on the type of object.

In addition, campaign and ad objects have an is_active attribute, which indicates whether or not the object has been deleted, and is independent of the object’s status attribute.

Campaign Statuses

Status Description
approved The campaign has been approved by AdRoll admin and submitted to the appropriate network(s).
paused The campaign has been paused by a user or an AdRoll admin, and is not serving any ads.
admin_review The campaign is undergoing review by an AdRoll admin and has not been approved or rejected yet.
completed The campaign’s end date has elapsed and the campaign is no longer eligible to serve ads.
draft The campaign is in draft state and has not yet been launched.
admin_paused The campaign has been suspended by the AdRoll review team, sometimes due to conflicts with creative requirements. See Creative Requirements for details on creative requirements.
cancelled The campaign has been cancelled by an AdRoll admin.
rejected The campaign is not compliant with site policy or requirements. See Website Content for details on site policy and requirements.

Ad Statuses

Status Description
approved The ad has been approved by an AdRoll admin. If it is included as active in any currently running adgroups, it is serving impressions in those adgroups. An “approved” ad can be marked as “paused” in a specific adgroup, in which case, it will not serve impressions in that adgroup.
paused The ad has been paused by a user or an AdRoll admin. If it is included in any adgroups, it is not serving impressions in those adgroups.
admin_review The ad is undergoing review from an AdRoll admin. If it is included in any adgroups, it will not serve impressions in those adgroups until it is approved.
admin_paused The ad has been paused by an AdRoll admin. If it is included in any adgroups, it is not serving impressions in those adgroups. This is sometimes due to conflicts with creative requirements. See Creative Requirements for details on creative requirements.
kicked The ad has been rejected by a network or removed by a user or an AdRoll admin. If it is included in any adgroups, it is not serving impressions in those adgroups.