Automated Campaigns API Reference

Note

If you use the APIs provided here, you are subject to the API Terms of Use, and Service Privacy Notice

Note

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

Description

AdRoll Automated Campaigns API (v1) 1.0

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 NextRoll Developer site

Responses:

200

A list of Campaign objects

Schema as JSON:

{
  "data": [
    {
      "adgroup_eid": "string",
      "budget": 0.0,
      "campaign_eid": "string",
      "created_at": "string",
      "eid": "string",
      "product": "string",
      "strategy_eid": "string",
      "updated_at": "string",
      "weekly_budget": 0.0
    }
  ]
}
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 NextRoll Developer site

Schema for request body:

{
  "status": "string"
}
Schema
Type

object

status

Status to set the campaign to

Type

string

Enum

live, paused

Responses:

200

A Campaign object

Schema as JSON:

{
  "data": {
    "adgroup_eid": "string",
    "budget": 0.0,
    "campaign_eid": "string",
    "created_at": "string",
    "eid": "string",
    "product": "string",
    "strategy_eid": "string",
    "updated_at": "string",
    "weekly_budget": 0.0
  }
}
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 NextRoll Developer site

Responses:

200

A list of Strategy objects

Schema as JSON:

{
  "data": [
    {
      "advertisable_eid": "string",
      "budget": 0.0,
      "campaigns": [
        {
          "adgroup_eid": "string",
          "budget": 0.0,
          "campaign_eid": "string",
          "created_at": "string",
          "eid": "string",
          "product": "string",
          "strategy_eid": "string",
          "updated_at": "string",
          "weekly_budget": 0.0
        }
      ],
      "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"
      ],
      "spend_floor": 0.0,
      "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 NextRoll 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",
  "negative_segments": [
    "string"
  ],
  "positive_segments": [
    "string"
  ],
  "products": [
    "string"
  ],
  "spend_floor": 0.0,
  "start_date": "string"
}

Responses:

200

The newly created strategy

Schema as JSON:

{
  "data": {
    "advertisable_eid": "string",
    "budget": 0.0,
    "campaigns": [
      {
        "adgroup_eid": "string",
        "budget": 0.0,
        "campaign_eid": "string",
        "created_at": "string",
        "eid": "string",
        "product": "string",
        "strategy_eid": "string",
        "updated_at": "string",
        "weekly_budget": 0.0
      }
    ],
    "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"
    ],
    "spend_floor": 0.0,
    "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 NextRoll Developer site

Schema for request body: StrategyEdit

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

Responses:

200

The updated strategy

Schema as JSON:

{
  "data": {
    "advertisable_eid": "string",
    "budget": 0.0,
    "campaigns": [
      {
        "adgroup_eid": "string",
        "budget": 0.0,
        "campaign_eid": "string",
        "created_at": "string",
        "eid": "string",
        "product": "string",
        "strategy_eid": "string",
        "updated_at": "string",
        "weekly_budget": 0.0
      }
    ],
    "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"
    ],
    "spend_floor": 0.0,
    "start_date": "string",
    "status": "string"
  }
}
Schema
Type

object

data
Type

StrategyResponse

Definitions

StrategyResponse
Type

object

eid

EID of strategy. 22 characters long.

Type

string

MaxLength

22

MinLength

22

advertisable_eid

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

Type

string

MaxLength

22

MinLength

22

budget

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

Type

number

Format

float

name
Type

string

MaxLength

64

start_date

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

Type

string

Format

date-time

end_date

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

Type

string

Format

date-time

currency

ISO-4217 currency code

Type

string

status

Status of strategy

Type

string

Enum

paused, live

spend_floor

Percentage representing how low the budget fulfillment can go to try to attain the user kpi. - 1 means our algorithm will always try to maximize budget fulfillment (recommended). - 0 means our algorithm might stop spending if that’s needed to reach the user KPI goal. You can use the numbers in between to tune our algorithm.

Type

number

Format

float

Maximum

1

kpi_goal

Value of KPI goal for specified KPI metric (in currency specified by currency parameter).It can be null to indicate that Adroll optimizes the KPI goal for the user.

Type

number

Format

float

kpi_metric

Metric used to measure KPI.

Type

string

Enum

CPA, CPC, CPM

created_at

Datetime of strategy creation in ISO-8601 in UTC.

Type

string

Format

date-time

campaigns
Type

array of CampaignResponse

products

Products in the strategy.

Type

array of items

email
Type

Email

CampaignResponse
strategy_eid

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

Type

string

MaxLength

22

MinLength

22

eid

EID of campaign. 22 characters long.

Type

string

MaxLength

22

MinLength

22

campaign_eid

EID of campaign. 22 characters long.

Type

string

MaxLength

22

MinLength

22

adgroup_eid

EID of the campaign adgroup. 22 characters long.

Type

string

MaxLength

22

MinLength

22

budget

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

Type

number

Format

float

weekly_budget

Weekly representation of the campaing’s budget in the currency specified by the strategies’s currency. It is equivalent to budget * 7.

Type

number

Format

float

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

StrategyCreate
budget

Daily Budget for strategy in currency specified by currency parameter.

Required

True

Type

number

Format

float

currency

The ISO-4217 currency code of the strategy budget.

Required

True

Type

string

Enum

USD, EUR, AUD, GBP, NZD, JPY

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

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

ad_eids

List of EIDs of existing ads.

Type

array of items

kpi_goal

Value of KPI goal for specified KPI metric (in currency specified by currency parameter). Must be less than the budget. Set it to null to let Adroll optimize the KPI goal for you.

Required

True

Type

number

Format

float

kpi_metric

Metric used to measure KPI.

Required

True

Type

string

Enum

CPA, CPC, CPM

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

negative_segments
Type

array of items

email
Type

Email

spend_floor

Percentage representing how low the budget fulfillment can go to try to attain the user kpi. - 1 means our algorithm will always try to maximize budget fulfillment (recommended). - 0 means our algorithm might stop spending if that’s needed to reach the user KPI goal. You can use the numbers in between to tune our algorithm.

Type

number

Format

float

Maximum

1

StrategyEdit
budget

Daily Budget for strategy in currency specified by currency parameter.

Type

number

Format

float

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

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

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. Set it to null to let Adroll optimize the KPI goal for you.

Type

number

Format

float

kpi_metric

Metric used to measure KPI.

Type

string

Enum

CPA, CPC, CPM

spend_floor

Percentage representing how low the budget fulfillment can go to try to attain the user kpi. - 1 means our algorithm will always try to maximize budget fulfillment (recommended). - 0 means our algorithm might stop spending if that’s needed to reach the user KPI goal. You can use the numbers in between to tune our algorithm.

Type

number

Format

float

Maximum

1

Email
optin

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

Type

boolean

optin_country

Supported ISO-3166 country code for advertisable.

Type

string

sender_name

Name of sender for emails sent by AdRoll Email.

Type

string

sender_address

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

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