Integration Guide for Reporting Platforms

The most common use for the AdRoll API is to retrieve reporting data. If you’re a reporting platform that’s interested in supporting AdRoll, this is the guide for you.

For existing AdRoll users, you can find a list of supported reporting platforms on the help center.

Interested in partnering get in contact by filling out the form. If you have any API questions, you can contact the API team.

Get to know the AdRoll API

Before you start building your integration, it helps to have a basic understanding of AdRoll and the AdRoll API.

Get Started with the AdRoll API will help you make your first API call.

Get to know AdRoll provides an overview of the AdRoll object structure and defines common terminology.

Authentication

Use OAuth 2.0 to gain access to a user’s AdRoll account. Our OAuth 2.0 implementation is compatible with standard libraries. You should be able to plug-in our token and authorization URLs into your favorite library.

See also:

Retrieve Reporting

To retrieve reporting data, you can use the AdRoll GraphQL Reporting API.

In this example query, we retrieve data most AdRoll users are interested in. See AdRoll GraphQL Reporting API Schema for the complete list of available data.

Example GraphQL query
query AllAdvertisables {
  advertisable {
    forUser {
      eid
      name
      campaigns {
        eid
        name
        type
        metrics(start: $startDate, end: $endDate) {
          byDate {
            date
            ...performanceMetrics
            ...conversionMetrics
          }
        }
      }
      adgroups {
        eid
        name
        metrics(start: $startDate, end: $endDate) {
          byDate {
            date
            ...performanceMetrics
            ...conversionMetrics
          }
        }
        audiences {
          eid
          name
          type
          metrics(start: $startDate, end: $endDate) {
            summary {
              ...audienceMetrics
            }
          }
        }
      }
      ads {
        eid
        name
        metrics(start: $startDate, end: $endDate) {
          byDate {
            date
            ...performanceMetrics
            ...conversionMetrics
          }
        }
      }
    }
  }
}

fragment performanceMetrics on Metric {
  cost
  impressions
  clicks
  ctr
  cpm
  cpc
}

fragment conversionMetrics on Metric {
  conversions
  cpa
  clickThroughs
  clickCPA
  viewThroughs
  viewCPA
}

fragment audienceMetrics on AudienceMetric {
  totalVisitors
  newVisitors
  currentVisitors
  currentVisitorsInDateRange
}

Note

For readability and to reduce duplication, we’re using GraphQL’s fragments and variables features.

Example variables:

GraphQL variable definitions used in the example query
{
  "startDate": "2017-12-09",
  "endDate":"2017-12-10"
}

You combine the above query and variables into a JSON POST request:

Example HTTP POST request
POST /reporting/api/v1/query HTTP/1.1
Host: services.adroll.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "query": "....",
  "operationName": "AllAdvertisables",
  "variables": { "startDate": "2017-12-09", "endDate":"2017-12-10" }
}

The response with be a JSON object that mirrors the structure of the input query:

Example response
{
  "data": {
    "advertisable": {
      "forUser": [
        {
          "eid": "C5355E63986CA41AA7207F",
          "name": "Test Advertisable",
          "adgroups": [],
          "ads": [
            {
              "eid": "7588D18F396772CED83501",
              "name": "160x600",
              "metrics": {
                "byDate": [
                  {
                    "clickCPA": null,
                    "clickThroughs": null,
                    "clicks": null,
                    "conversions": null,
                    "cost": null,
                    "cpa": null,
                    "cpc": null,
                    "cpm": null,
                    "ctr": null,
                    "date": "2017-12-09",
                    "impressions": null,
                    "viewCPA": null,
                    "viewThroughs": null
                  }
                ]
              }
            }
          ],
          "campaigns": [
            {
              "eid": "A48AAB0081005DDB968258",
              "name": "My Facebook Retargeting Campaign",
              "type": "retargeting",
              "metrics": {
                "byDate": [
                  {
                    "clickCPA": null,
                    "clickThroughs": null,
                    "clicks": null,
                    "conversions": null,
                    "cost": null,
                    "cpa": null,
                    "cpc": null,
                    "cpm": null,
                    "ctr": null,
                    "date": "2017-12-09",
                    "impressions": null,
                    "viewCPA": null,
                    "viewThroughs": null
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  },
  "(~˘▾˘)~": "2017.12.11-1/req160053",
  "request": "req160053",
  "version": "2017.12.11-1"
}

See also:

Final Touches

Once you’re ready to launch you’re integration, send us an email and we’ll add you to the list of supported reporting platforms on the help center. We’ll also increase your API quota.

See the AdRoll brand guidelines for logos and AdRoll Voice and Tone for how to best represent AdRoll.

Get Help

Have questions or need help? Send us an email.