AdRoll CRUD API Overview

The AdRoll Advertiser API is implemented as JSON over HTTP using all four verbs (GET, POST, PUT, DELETE). Each resource, like Advertisers, Campaigns, Ads, has its own URL and is manipulated in isolation. In other words, we’ve tried to make the API follow the REST principles as much as possible.

Authentication

All requests to AdRoll’s REST API require you to authenticate. Use basic HTTP auth with your AdRoll username and password when making requests. Please contact AdRoll to enable your account for API usage.

Getting Started

The AdRoll CRUD API Usage page shows general API concepts.

Service Walk-through

The objects of AdRoll model form a likely familiar (e.g., AdWords-esque) hierarchy. Each level of the hierarchy from Advertisable down has an equivalent API service.

AdRoll model hierarchy
  • Organization - an account representing a single billing entity (e.g., “Ad Agency”)
    • Advertisable 1 - an advertising profile representing a brand (e.g., “Bob’s Pets”)

    • Advertisable ...

    • Advertisable N
      • Pixel - a single pixel (HTML snippet) that the advertiser places on their site

      • Segment 1 - a user segment (e.g., “First-time buyers”) to target

      • Segment ...

      • Segment N

      • Ad 1 - an IAB ad creative (e.g., “300x250 image ad”)

      • Ad ...

      • Ad N

      • Campaign 1 - a campaign associated with a date range and budget (e.g., “Holiday Blitz”)

      • Campaign ...

      • Campaign N
        • AdGroup 1 - used to pair a set of ads with a set of targeting criteria

        • AdGroup ... (e.g., retargeting ad group)
          • Selected Segments
          • Selected Ads
        • AdGroup N (e.g., site-targeted ad group)
          • Selected Sites
          • Selected Ads

Each organization (e.g., an agency) can have a number of advertisables (e.g., specific brands they represent). Within an advertisable, you can have a pixel used for retargeting. Each pixel in turn has a list of segments that are tracked. Segments are typically used to cookie a group of visitors to a URL or set of URLs on an advertiser’s site. The advertisable also has a list of ads (e.g., “an ad library”) associated with it. Under an advertisable, you can also run any number of campaigns. The campaign consists of adgroups, which allow you to associate targeting and a set of ads. Within each adgroup, you select ads from the ad library, and targeting criteria. The targeting criteria is based on a selection of predefined segments and geolocations.

Each object is referred to with a unique id (called an “EID” or external id) which consists of 22 alphanumeric characters (e.g., “AX4BDADOHNFIDLETVWBLY3”).