CRUD API Usage¶

REST Semantics¶

The CRUD 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	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://services.adroll.com/api/v1/ad?apikey=MYAPIKEY&name=My+Ad&eid=XJCACTZQ2RHKRHU34YPFXQ

POST https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY&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://services.adroll.com/api/v1/ad?apikey=MYAPIKEY&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 returned 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://services.adroll.com/api/v1/ad?apikey=MYAPIKEY

//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 an admin and submitted to the appropriate network(s).
`paused`	The campaign has been paused by a user or an admin, and is not serving any ads.
`admin_review`	The campaign is undergoing review by an 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 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 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 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 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 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 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 admin. If it is included in any adgroups, it is not serving impressions in those adgroups.