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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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 Personal Access Tokens (PAT). 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