Automated Campaigns API Reference

Note

If you use the APIs provided here, you are subject to the API Terms of Use, and AdRoll Services Privacy Note

Note

We’ve introduced API keys, please read Migrating to API Keys

Description

AdRoll Automated Campaigns API (v1) 1.0 by AdRoll

Create and edit AdRoll strategies with the AdRoll Automated Campaigns API

Operations

GET /activate/api/v1/campaign

Fetch campaigns for a given strategy

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string Advertisable EID of requested strategy
strategy_eid True string Strategy EID of requested campaign
campaign_eid False string Campaign EID (if fetching a specific campaign)
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

A list of Campaign objects

Schema as JSON:

{
  "data": [
    {
      "budget": 0.0, 
      "created_at": "string", 
      "eid": "string", 
      "product": "string", 
      "strategy_eid": "string", 
      "updated_at": "string"
    }
  ]
}
Schema
Type:object
data
Type:array of CampaignResponse
PUT /activate/api/v1/campaign

Modify a specific campaign

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string Advertisable EID of requested strategy
strategy_eid True string Strategy EID of requested campaign
campaign_eid True string Campaign EID to modify
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

{
  "status": "string"
}
Schema
Type:object
status

Status to set the campaign to

Type:string
Enum:paused, live

Responses:

200 OK

A Campaign object

Schema as JSON:

{
  "data": {
    "budget": 0.0, 
    "created_at": "string", 
    "eid": "string", 
    "product": "string", 
    "strategy_eid": "string", 
    "updated_at": "string"
  }
}
Schema
Type:object
data
Type:CampaignResponse
GET /activate/api/v1/strategy

Fetch strategy

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string Advertisable EID of requested strategy
strategy_eid False string Strategy EID of requested strategy
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

A list of Strategy objects

Schema as JSON:

{
  "data": [
    {
      "advertisable_eid": "string", 
      "budget": 0.0, 
      "campaigns": [
        {
          "budget": 0.0, 
          "created_at": "string", 
          "eid": "string", 
          "product": "string", 
          "strategy_eid": "string", 
          "updated_at": "string"
        }
      ], 
      "created_at": "string", 
      "currency": "string", 
      "eid": "string", 
      "email": {
        "emails": [
          {
            "body": "string", 
            "cta_destination": "string", 
            "cta_label": "string", 
            "email_subject": "string", 
            "headline": "string", 
            "hero_image_url": "string"
          }
        ], 
        "footer_postal_address": "string", 
        "optin": true, 
        "optin_country": "string", 
        "sender_address": "string", 
        "sender_name": "string"
      }, 
      "end_date": "string", 
      "kpi_goal": 0.0, 
      "kpi_metric": "string", 
      "name": "string", 
      "products": [
        "string"
      ], 
      "start_date": "string", 
      "status": "string"
    }
  ]
}
Schema
Type:object
data
Type:array of StrategyResponse
POST /activate/api/v1/strategy

Create a new strategy.

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string Advertisable EID of requested strategy
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body: StrategyCreate

{
  "ad_eids": [
    "string"
  ], 
  "budget": 0.0, 
  "currency": "string", 
  "email": {
    "emails": [
      {
        "body": "string", 
        "cta_destination": "string", 
        "cta_label": "string", 
        "email_subject": "string", 
        "headline": "string", 
        "hero_image_url": "string"
      }
    ], 
    "footer_postal_address": "string", 
    "optin": true, 
    "optin_country": "string", 
    "sender_address": "string", 
    "sender_name": "string"
  }, 
  "end_date": "string", 
  "kpi_goal": 0.0, 
  "kpi_metric": "string", 
  "name": "string", 
  "negative_segments": [
    "string"
  ], 
  "positive_segments": [
    "string"
  ], 
  "products": [
    "string"
  ], 
  "start_date": "string"
}

Responses:

200 OK

The newly created strategy

Schema as JSON:

{
  "data": {
    "advertisable_eid": "string", 
    "budget": 0.0, 
    "campaigns": [
      {
        "budget": 0.0, 
        "created_at": "string", 
        "eid": "string", 
        "product": "string", 
        "strategy_eid": "string", 
        "updated_at": "string"
      }
    ], 
    "created_at": "string", 
    "currency": "string", 
    "eid": "string", 
    "email": {
      "emails": [
        {
          "body": "string", 
          "cta_destination": "string", 
          "cta_label": "string", 
          "email_subject": "string", 
          "headline": "string", 
          "hero_image_url": "string"
        }
      ], 
      "footer_postal_address": "string", 
      "optin": true, 
      "optin_country": "string", 
      "sender_address": "string", 
      "sender_name": "string"
    }, 
    "end_date": "string", 
    "kpi_goal": 0.0, 
    "kpi_metric": "string", 
    "name": "string", 
    "products": [
      "string"
    ], 
    "start_date": "string", 
    "status": "string"
  }
}
Schema
Type:object
data
Type:StrategyResponse
PUT /activate/api/v1/strategy

Edit an existing strategy.

Parameters:

Query Parameters
Name Required Type Description
advertisable_eid True string Advertisable EID of requested strategy
strategy_eid True string Strategy EID
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body: StrategyEdit

{
  "budget": 0.0, 
  "end_date": "string", 
  "kpi_goal": 0.0, 
  "kpi_metric": "string", 
  "start_date": "string", 
  "status": "string"
}

Responses:

200 OK

The updated strategy

Schema as JSON:

{
  "data": {
    "advertisable_eid": "string", 
    "budget": 0.0, 
    "campaigns": [
      {
        "budget": 0.0, 
        "created_at": "string", 
        "eid": "string", 
        "product": "string", 
        "strategy_eid": "string", 
        "updated_at": "string"
      }
    ], 
    "created_at": "string", 
    "currency": "string", 
    "eid": "string", 
    "email": {
      "emails": [
        {
          "body": "string", 
          "cta_destination": "string", 
          "cta_label": "string", 
          "email_subject": "string", 
          "headline": "string", 
          "hero_image_url": "string"
        }
      ], 
      "footer_postal_address": "string", 
      "optin": true, 
      "optin_country": "string", 
      "sender_address": "string", 
      "sender_name": "string"
    }, 
    "end_date": "string", 
    "kpi_goal": 0.0, 
    "kpi_metric": "string", 
    "name": "string", 
    "products": [
      "string"
    ], 
    "start_date": "string", 
    "status": "string"
  }
}
Schema
Type:object
data
Type:StrategyResponse

Definitions

StrategyCreate
negative_segments
Type:array of items
name

descriptive name

Type:string
MaxLength:64
end_date

Date to stop running the strategy on in ISO-8601 format If omitted, the strategy will run forever. If a timezone is not specified it will be assumed to be UTC.

Type:string
Format:date-time
kpi_goal

Value of KPI goal for specified KPI metric (in currency specified by currency parameter). Must be less than the budget.

Required:True
Type:number
Format:float
budget

Daily Budget for strategy in currency specified by currency parameter.

Required:True
Type:number
Format:float
email
Type:Email
ad_eids

List of EIDs of existing ads.

Type:array of items
currency

The ISO-4217 currency code of the strategy budget.

Required:True
Type:string
Enum:USD, EUR, AUD, GBP, NZD, JPY
products

Products to initialize campaigns with on this strategy. Web is required. You have the option of also running on Facebook.

Required:True
Type:array of items
positive_segments
Type:array of items
start_date

Date to start running the strategy on in ISO-8601 format If omitted, the current date will be used. If a timezone is not specified it will be assumed to be UTC.

Type:string
Format:ISO-8601
kpi_metric

Metric used to measure KPI.

Required:True
Type:string
Enum:CPA, CPC, CPM
StrategyResponse
Type:object
status

Status of strategy

Type:string
Enum:paused, live
advertisable_eid

EID of advertisable strategy is attached to. 22 Characters long.

Type:string
MaxLength:22
MinLength:22
name
Type:string
MaxLength:64
end_date

End date of strategy in ISO-8601 format in UTC.

Type:string
Format:date-time
created_at

Datetime of strategy creation in ISO-8601 in UTC.

Type:string
Format:date-time
kpi_goal

Value of KPI goal for specified KPI metric (in currency specified by currency parameter).

Type:number
Format:float
budget

Daily budget of strategy in the currency specified by the currency field.

Type:number
Format:float
email
Type:Email
campaigns
Type:array of CampaignResponse
currency

ISO-4217 currency code

Type:string
products

Products in the strategy.

Type:array of items
eid

EID of strategy. 22 characters long.

Type:string
MaxLength:22
MinLength:22
start_date

Start date/time of strategy in ISO-8601 format in UTC.

Type:string
Format:date-time
kpi_metric

Metric used to measure KPI.

Type:string
Enum:CPA, CPC, CPM
CampaignResponse
strategy_eid

EID of the strategy the campaign is attached to. 22 characters long.

Type:string
MaxLength:22
MinLength:22
product

Product of campaign

Type:string
Enum:web, fb, email
created_at

Datetime of campaign creation in ISO-8601 format in UTC.

Type:string
Format:date-time
updated_at

Datetime of last campaign update in ISO-8601 format in UTC.

Type:string
Format:date-time
budget

Continuously optimized daily budget for campaign in currency specified by the strategy’s currency parameter.

Type:number
Format:float
eid

EID of campaign. 22 characters long.

Type:string
MaxLength:22
MinLength:22
Email
sender_name

Name of sender for emails sent by AdRoll Email.

Type:string
optin

Boolean indicating whether or not the user has opted in to use AdRoll Email.

Type:boolean
sender_address

Email address to use as the sender email for emails sent by AdRoll Email.

Type:string
optin_country

ISO-3166 country code for advertisable.

Type:string
footer_postal_address

Postal address of business to place in the footer of emails sent by AdRoll Email.

Type:string
emails
Type:array of items
StrategyEdit
status

Status of strategy. By default all strategies are created in the live state and will begin spending immediately. Pausing a strategy will pause all underlying campaigns. Resuming a strategy will resume resume all underlying campaigns that were paused by the strategy. (Individual campaigns can be paused independently - resuming a strategy will not resume these manually paused campaigns.)

Type:string
Enum:paused, live
end_date

Date to stop running the strategy on in ISO-8601 format If a timezone is not specified it will be assumed to be UTC.

Type:string
Format:date-time
kpi_goal

Value of KPI goal for specified KPI metric (in currency specified by currency parameter). Must be less than the budget.

Type:number
Format:float
budget

Daily Budget for strategy in currency specified by currency parameter.

Type:number
Format:float
start_date

Date to start running the strategy on in ISO-8601 format Start date cannot be edited if the strategy is already running

Type:string
Format:ISO-8601
kpi_metric

Metric used to measure KPI.

Type:string
Enum:CPA, CPC, CPM