Campaigns

This article describes services for reading, adding, and updating updating campaigns.

Overview

In Oath Ad Platforms DSP, a campaign is an advertising goal that defines a strategy for delivering ads within a set time period. Campaigns are defined by start and end dates, budgets, frequency cap settings, an optional demographic targeting data provider, and campaign goal settings (to measure campaign effectiveness).

Every campaign belongs to a specific advertiser and inherits default settings (time zone, currency, etc.) from the advertiser-level settings. Campaign-level flight dates (start and end dates), frequency capping, and budget settings constrain line-level settings.

Campaign budgets may be defined by two alternative methods:

  • A single budget that applies to all lines in the campaign as defined by the dailyBudgetType, dailyBudget, totalBudgetType, budget, campaignStartDate, and campaignEndDate.
  • Multiple budget schedules that may be applied to the lines within the campaign as defined in the budgetSchedules array.

Hierarchy

A Campaign is an advertiser-level object.

Endpoint

You can use this endpoint to read, create, and update campaign objects.

/traffic/campaigns

The action taken depends on the HTTP method and the parameters specified.

  • Use the GET method to read existing campaigns.
  • Use the POST method to create new campaigns.
  • Use the PUT method to update existing campaigns.

Resources

Campaign Object

The campaign object contains the following fields:

Table 83 Campaign Object Parameters
Fields Description Data Type Create Update
id Specifies the ID of the campaign. integer N/A Y
name Specifies the name of the campaign. string Y N
status

Specifies the current status of the campaign. Options include:

  • ACTIVE
  • PAUSED
  • INACTIVE

In addition, the resource may return the following read-only statuses:

  • STOP_TOTAL_BUDGET: Indicates that the total budget has been reached.
  • STOP_DAILY_BUDGET: Indicates that daily budget has been reached.
  • NOT_STARTED: Indicates that the campaign has not started.
  • ENDED: Indicates that the campaign has ended.
  • NO_ADS_ADDED: Indicates that no ads have been added to the campaigns.
  • ERROR: Indicates that an error occurred.
string Y N
goalType

Specifies the KPI used to measure the success of the campaign. Options include:

  • CTR
  • CPC
  • CPA
  • CPCV
  • VCPM
  • ROAS
string Y N
goalValue

Specifies target goal type-specific value. The target value for the goalType.

Note: If goalType is set to CTR, this value must be a percentage between 0 and 100.

number Y N
frequencyCapPeriodType

Specifies the frequency capping method. Options include:

  • UNLIMITED: Frequency capping is set for each line in the campaign.
  • MINUTES: Frequency capping is defined at the campaign level to the minute.
  • HOURLY: Frequency capping is defined on a hourly basis at the campaign level.
  • DAILY: Frequency capping is defined on a daily basis at the campaign level.
  • WEEKLY: Frequency capping is defined on a weekly basis at the campaign level.
  • MONTHLY: Frequency capping is defined on a monthy basis at the campaign level.
string N N
frequencyCapValue Specifies the maximum number of impressions to serve per the frequencyCapPeriodType. number N N
demoVendor

Specifies the demographic targeting data provider for video campaigns.

The Oath Ad Platforms DSP uses Yahoo and third-party data verification vendors to provide targeting verification when you set up demographic targeting for video ads. Options include:

  • YAHOO
  • COMSCORE
  • NIELSEN

Important: Once the campaign is created, this value can not be changed.

string N N
timezone

Specifies the time zone of the campaign.

If undefined or set to null, the advertiser time zone is used.

Note: Once a campaign is saved, the timezone attribute cannot be updated.

string N N
currency

Specifies the currency in the campaign.

If unspecified or set to null, the campaign uses the advertiser-level currency settings. To learn more, see Currency Types.

string N N
accountId

Specifies the advertiser’s account ID.

To learn more, see Advertisers.

integer Y N
budgetSchedules

Specifies an array of Budget Schedule objects.

A Budget Schedule defines a budget that can be used to define lines within a campaign. To learn more, see Budget Schedule Object.

Important: If you the budgetSchedules array is defined and not empty, the dailyBudgetType, dailyBudget, totalBudgetType, budget, campaignStartDate, and campaignEndDate attributes must be omitted or set to null.

array N N
dailyBudgetType

Specifies the daily budget type. Options include:

  • TOTAL_BUDGET: By default, the entire campaign budget is available.
  • SPECIFIED_AMOUNT: If specified, you may define a daily spending cap in the dailyBudget parameter.
  • AUTO_ALLOCATED: If specified, the remaining budget is automatically allocated at a regular rate across the duration of the campaign.

If the budgetSchedules array is defined, the dailyBudgetType must be omitted or set to null.

string N N
dailyBudget

Specifies the daily budget.

If the budgetSchedules array is defined, the dailyBudget must be omitted or set to null.

[1]Required if dailyBudgetType is SPECIFIED_AMOUNT.
number N [1] N
totalBudgetType

Specifies the total budget type. Options include:

  • SPECIFIED_AMOUNT: If specified, the total campaign budget is capped by the value specified in the budget parameter.
  • UNLIMITED: If specified, the campaign budget is unlimited.

If the budgetSchedules array is defined, the totalBudgetType must be omitted or set to null.

string N N
budget

Specifies the total budget for the campaign.

If the budgetSchedules array is defined, the budget must be omitted or set to null.

[2]Required if the totalBudgetType is SPECIFIED_AMOUNT
number N [2] N
campaignStartDate

Specifies the beginning of the campaign in yyyy-MM-dd format.

[3]Required if a single budget is defined for the campaign. If the budgetSchedules array is defined, the campaignEndStart must be omitted or set to null.

Note: Start time depends on the campaign’s time zone.

string N [3] N
campaignEndDate

Specifies the end of the campaign in yyyy-MM-dd format.

If the budgetSchedules array is defined, the campaignEndDate must be omitted or set to null.

string N N

Budget Schedule Object

A Budget Schedule defines a budget that can be used to define lines within a campaign.

The campaign object’s budgetSchedules array defines one or more Budget Schedule objects, which are defined by the scheduleName, startDate, endDate, scheduleBudgetType, and scheduleBudget attributes.

If the budgetSchdule object attributes are specified, the corresponding campaign object attributes must be set to null.

Note

You can specify a campaign budget using campaign object’s dailyBudget, dailyBudgetType, totalBudgetType, and budget attributes.

Once specified, budget schedules cannot be removed from a campaign. Budget schedule date range cannot overlap.

Table 84 Budget Schedule Object Attributes
Field Description Data Type Create Update
id Specifies the budget schedule ID. integer N/A Y
scheduleName Specifies a unique name for the budget schedule. string Y N
startDate

Specifies the beginning of the campaign in yyyy-MM-dd format.

If specified, the campaign object’s campaignStartDate must be set to null.

string Y N
endDate

Specifies the ending of the campaign in yyyy-MM-dd format.

If specified, the campaign object’s campaignStartDate must be set to null.

string Y N
scheduleBudgetType

Specifies the method used to allocate spending in the budget schedule. Options include:

  • TOTAL_BUDGET: If specified, the entire campaign budget is available.
  • SPECIFIED_AMOUNT: If specified, you may define a daily spending cap in the dailyBudget parameter.
  • AUTO_ALLOCATED: If specified, the remaining budget is automatically allocated at a regular rate across the duration of the campaign.

If specified, the campaign object’s dailyBudgetType must be set to null.

string N N
scheduleBudget

Specifies the total budget for the budget schedule.

[5]Required if the scheduleBudgetType is SPECIFIED_AMOUNT.
string N [5] N

Read Campaigns by ID

Reads campaign data for a specific campaign as identified by its campaign ID.

GET /traffic/campaigns/{id}

The response returns a single matching campaign.

Parameters

The id parameter is specified in the path of the endpoint URL.

Table 85 Read Campaign by ID Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the campaign ID. integer Y

The response will be the Campaign associated with the given ID.

Example Request

GET /traffic/campaigns/364677

Example Response

{
  "response": {
    "status": "ACTIVE",
    "totalBudgetType": "UNLIMITED",
    "dailyBudgetType": "TOTAL_BUDGET",
    "goalType": "CTR",
    "frequencyCapPeriodType": "DAILY",
    "timezone": "America/Los_Angeles",
    "currency": "USD",
    "campaignStartDate": "2018-03-10T08:00:00Z",
    "campaignEndDate": "2018-03-16T07:00:00Z",
    "id": 364677,
    "name": "test budget3",
    "createdAt": "2017-09-21T20:45:50Z",
    "updatedAt": "2017-09-21T20:45:50Z",
    "goalValue": 0,
    "frequencyCapValue": 10,
    "accountId": 1356341,
    "budget": null,
    "dailyBudget": 3
  },
  "errors": null,
  "timeStamp": "2017-09-21T20:45:49Z"
}

Read Campaigns by Query

Read campaign data for a filtered list of campaigns.

GET /traffic/campaigns?accountId={accountId}&page={page}&limit={limit}&sort={sort}&dir={dir}&query={query}

The response returns a list of matching campaigns.

Parameters

All parameters are specified in a query string that is appended to the endpoint URL.

Table 86 Read Campaign by Query Parameters
Parameter Parameter Type Description Data Type Required
accountId query Specifies the advertiser account ID. integer Y
page query Specifies the page number. integer N
limit query Specifies total number of items to return. Maximum allowed value is 100. integer N
sort query Specifies the column to sort by. integer N
dir query Specifies the sort direction. string N
query query Specifies a search term. Use URL encoding conventions (for example, a space should be replaced with a + or %20). string N

Example Request

GET /traffic/campaigns?accountId=1356341&page=1&limit=2&query=test+order

Example Response

{
  "response": [
    {
      "status": "ACTIVE",
      "totalBudgetType": "UNLIMITED",
      "dailyBudgetType": "TOTAL_BUDGET",
      "goalType": "CTR",
      "frequencyCapPeriodType": "DAILY",
      "timezone": "America/Los_Angeles",
      "currency": "USD",
      "campaignStartDate": "2018-03-10T08:00:00Z",
      "campaignEndDate": "2018-03-16T07:00:00Z",
      "id": 364677,
      "name": "test budget3",
      "createdAt": "2017-09-21T20:45:50Z",
      "updatedAt": "2017-09-21T20:45:50Z",
      "goalValue": 0,
      "frequencyCapValue": 10,
      "accountId": 1356341,
      "budget": null,
      "dailyBudget": 3
    },
    {
      "status": "ACTIVE",
      "goalType": "CTR",
      "frequencyCapPeriodType": "DAILY",
      "timezone": "America/Los_Angeles",
      "currency": "USD",
      "budgetSchedule" : [
       {
         "Id":555555,
         "scheduleBudget":0.01,
         "scheduleBudgetType":"DAILY_BUDGET",
         "startDate":"2018-06-18",
         "EndDate":"2018-08-18",
         "scheduleName":"schedule1"
         }
      ],
       "id": 364677,
       "name": "test budget3",
       "createdAt": "2017-09-21T20:45:50Z",
       "updatedAt": "2017-09-21T20:45:50Z",
       "goalValue": 0,
       "frequencyCapValue": 10,
       "accountId": 1356341
        }
      ],
       "errors": null,
       "timeStamp": "2017-09-21T22:21:35Z"
  }

Update Campaigns

Updates an existing campaign.

PUT /traffic/campaigns/{id}

The response returns the updated campaign.

Parameters

All parameters are specified in the body of the application/json payload.

Table 87 Update Campaign Parameters
Parameter Parameter Type Description Data Type Required?
id path Specifies the ID of the campaign. integer Y
name body Specifies the name of the campaign. string N
status body

Specifies the current status of the campaign. Options include:

  • ACTIVE
  • PAUSED
  • INACTIVE
string N
goalType body

Specifies the KPI used to measure the success of the campaign. Options include:

  • CTR
  • CPC
  • CPA
  • CPCV
  • VCPM
  • ROAS
string N
goalValue body

Specifies target goal type-specific value. The target value for the goalType.

Note: If goalType is set to CTR, this value must be a percentage between 0 and 100.

number N
frequencyCapPeriodType body

Specifies the frequency capping method. Options include:

  • UNLIMITED: Frequency capping is set for each line in the campaign.
  • MINUTES: Frequency capping is defined at the campaign level to the minute.
  • HOURLY: Frequency capping is defined on a hourly basis at the campaign level.
  • DAILY: Frequency capping is defined on a daily basis at the campaign level.
  • WEEKLY: Frequency capping is defined on a weekly basis at the campaign level.
  • MONTHLY: Frequency capping is defined on a monthy basis at the campaign level.
string N
frequencyCapValue body Specifies the maximum number of impressions to serve per the frequencyCapPeriodType. number N
demoVendor body

Specifies the demographic targeting data provider for video campaigns.

The Oath Ad Platforms DSP uses Yahoo and third-party data verification vendors to provide targeting verification when you set up demographic targeting for video ads. Options include:

  • YAHOO
  • COMSCORE
  • NIELSEN

Important: Once the campaign is created, this value can not be changed.

string N
timezone body

Specifies the time zone of the campaign.

If undefined or set to null, the advertiser time zone is used.

Once a campaign is saved, the timezone attribute cannot be updated.

string N
currency body If unspecified or set to null, the campaign uses the advertiser-level currency settings. To learn more, see Currency Types. string N
accountId body Specifies the advertiser’s account ID. To learn more, see traffic/advertisers. integer N
budgetSchedules body

Specifies an array of Budget Schedule objects.

A Budget Schedule defines a budget that can be used to define lines within a campaign. To learn more, see Budget Schedule Object.

Important: If you the budgetSchedules array is defined, the dailyBudgetType, dailyBudget, totalBudgetType, budget, campaignStartDate, and campaignEndDate attributes must be omitted or set to null.

Once specified, budget schedules cannot be removed from a campaign. Budget schedule date range cannot overlap.

array N
dailyBudget body

Specifies the daily budget.

If the budgetSchedules array is defined, the dailyBudget must be omitted or set to null.

[4]Required if dailyBudgetType is SPECIFIED_AMOUNT.
number N [4]
dailyBudgetType body

Specifies the daily budget type. Options include:

  • TOTAL_BUDGET: By default, the entire campaign budget is available.
  • SPECIFIED_AMOUNT: If specified, you may define a daily spending cap in the dailyBudget parameter.
  • AUTO_ALLOCATED: If specified, the remaining budget is automatically allocated at a regular rate across the duration of the campaign.

If the budgetSchedules array is defined, the dailyBudgetType must be omitted or set to null.

string N
totalBudgetType body

Specifies the total budget type. Options include:

  • SPECIFIED_AMOUNT: If specified, the total campaign budget is capped by the value specified in the budget parameter.
  • UNLIMITED: If specified, the campaign budget is unlimited.

If the budgetSchedules array is defined, the totalBudgetType must be omitted or set to null.

string N
budget body

Specifies the total budget for the campaign.

If the budgetSchedules array is defined, the budget must be omitted or set to null.

[6]Required if the totalBudgetType is SPECIFIED_AMOUNT
number N [6]
campaignStartDate body

Specifies the beginning of the campaign in yyyy-MM-dd format.

If the budgetSchedules array is defined, the campaignStartDate must be omitted or set to null.

string N
campaignEndDate body

Specifies the end of the campaign in yyyy-MM-dd format.

If the budgetSchedules array is defined, the campaignEndDate must be omitted or set to null.

string N

Example Request

PUT https://dspapi.admanagerplus.yahoo.com/traffic/campaigns/364677

Example Payload

{
  "totalBudgetType": "SPECIFIED_AMOUNT",
  "budget": 7440.7,
  "goalType": "CPA",
  "campaignEndDate": "2018-03-16"
}

If budgetSchedules array is not empty, the following campaign object attributes must be set to null or absent in the payload:

  • campaignStartDate
  • campaignEndDate
  • totalBudgetType
  • Budget
  • dailyBudget
  • dailyBudgetType
{
   "name": "test new Name",
   "budgetSchedules" : [
    {
         "id":555555,
         "scheduleBudget":0.05,
         "scheduleBudgetType":"DAILY_BUDGET",
         "startDate":"2018-06-18",
         "endDate":"2018-08-19",
         "scheduleName":"schedule1"
      },
     {
         "id":555556,
         "scheduleBudget":0.02,
         "scheduleBudgetType":"TOTAL_BUDGET",
         "startDate":"2018-06-28",
         "endDate":"2018-08-30",
         "scheduleName":"schedule2"
      },
         ]
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "totalBudgetType": "SPECIFIED_AMOUNT",
    "dailyBudgetType": "TOTAL_BUDGET",
    "goalType": "CPA",
    "frequencyCapPeriodType": "DAILY",
    "timezone": "America/Los_Angeles",
    "currency": "USD",
    "campaignStartDate": "2018-03-10T08:00:00Z",
    "campaignEndDate": "2018-03-16T07:00:00Z",
    "id": 364677,
    "name": "test budget3",
    "createdAt": "2017-09-21T20:45:50Z",
    "updatedAt": "2017-09-21T22:51:15Z",
    "goalValue": 0,
    "frequencyCapValue": 10,
    "accountId": 1356341,
    "budget": 7440.7,
    "dailyBudget": 3
  },
  "errors": null,
  "timeStamp": "2017-09-21T22:51:15Z"
}

Create Campaigns

Creates a new campaign.

POST /traffic/campaigns

The response returns a newly created campaign.

Parameters

All parameters are specified in the body of the application/json payload.

Table 88 Create Campaign Parameters
Parameter Parameter Type Description Data Type Required?
name body Specifies the name of the campaign. string Y
status body

Specifies the current status of the campaign. Options include:

  • ACTIVE
  • PAUSED
  • INACTIVE
string Y
goalType body

Specifies the KPI used to measure the success of the campaign. Options include:

  • CTR
  • CPC
  • CPA
  • CPCV
  • VCPM
  • ROAS
string Y
goalValue body

Specifies target goal type-specific value. The target value for the goalType.

Note: If goalType is set to CTR, this value must be a percentage between 0 and 100.

number Y
frequencyCapPeriodType body

Specifies the frequency capping method. If not specified, defaults to UNLIMITED. Options include:

  • UNLIMITED: Frequency capping is set for each line in the campaign.
  • MINUTES: Frequency capping is defined at the campaign level to the minute.
  • HOURLY: Frequency capping is defined on a hourly basis at the campaign level.
  • DAILY: Frequency capping is defined on a daily basis at the campaign level.
  • WEEKLY: Frequency capping is defined on a weekly basis at the campaign level.
  • MONTHLY: Frequency capping is defined on a monthy basis at the campaign level.
string N
frequencyCapValue body Specifies the maximum number of impressions to serve per the frequencyCapPeriodType. number N
demoVendor body

Specifies the demographic targeting data provider for video campaigns.

The Oath Ad Platforms DSP uses Yahoo and third-party data verification vendors to provide targeting verification when you set up demographic targeting for video ads. Options include:

  • YAHOO
  • COMSCORE
  • NIELSEN

Important: Once the campaign is created, this value can not be changed.

string N
timezone body

Specifies the time zone of the campaign.

If undefined or set to null, the advertiser time zone is used.

Note: Once a campaign is saved, the timezone attribute cannot be updated. Use the tzId field from Timezones response. Some example values: America/New_York, Etc/GMT.

string N
currency body If you leave out this field or set it to null, Oath Ad Platforms DSP uses the currency set up for the advertiser by default. You can override the default currency when you create a campaign. To learn more, see Currency Types. string N
accountId body

Specifies the advertiser’s account ID.

To learn more, see Advertisers.

integer Y
budgetSchedules body

Specifies an array of Budget Schedule objects.

A Budget Schedule defines a budget that can be used to define lines within a campaign. To learn more, see Budget Schedule Object.

Important: If you the budgetSchedules array is defined, the dailyBudgetType, dailyBudget, totalBudgetType, budget, campaignStartDate, and campaignEndDate attributes must be omitted or set to null.

array N
dailyBudget body

Specifies the daily budget.

If the budgetSchedules array is defined, the dailyBudget must be omitted or set to null.

[7]Required if dailyBudgetType is SPECIFIED_AMOUNT.
number N [7]
dailyBudgetType body

Specifies the daily budget type. Options include:

  • TOTAL_BUDGET: By default, the entire campaign budget is available.
  • SPECIFIED_AMOUNT: If specified, you may define a daily spending cap in the dailyBudget parameter.
  • AUTO_ALLOCATED: If specified, the remaining budget is automatically allocated at a regular rate across the duration of the campaign.

If the budgetSchedules array is defined, the dailyBudgetType must be omitted or set to null.

string N
totalBudgetType body

Specifies the total budget type. Options include:

  • SPECIFIED_AMOUNT: If specified, the total campaign budget is capped by the value specified in the budget parameter.
  • UNLIMITED: If specified, the campaign budget is unlimited.

If the budgetSchedules array is defined, the totalBudgetType must be omitted or set to null.

string N
budget body

Specifies the total budget for the campaign.

If the budgetSchedules array is defined, the budget must be omitted or set to null.

[8]Required if the totalBudgetType is SPECIFIED_AMOUNT
number N [8]
campaignStartDate body

Specifies the beginning of the campaign in yyyy-MM-dd format.

If the budgetSchedules array is defined, the dailyBudget must be omitted or set to null.

string Y
campaignEndDate body

Specifies the end of the campaign in yyyy-MM-dd format.

If the budgetSchedules array is defined, the dailyBudget must be omitted or set to null.

string N

Example Request

No parameters are specified in the URL path.

POST /traffic/campaigns

All parameters are defined in the application/json payload.

{
  "name": "test budget4",
  "campaignStartDate": "2018-03-10",
  "campaignEndDate": "2018-03-16",
  "totalBudgetType": "UNLIMITED",
  "budget": null,
  "dailyBudget": 3,
  "dailyBudgetType": "TOTAL_BUDGET",
  "goalType": "CTR",
  "goalValue": 0,
  "accountId": 1356341,
  "currency": "USD",
  "status": "ACTIVE",
  "frequencyCapValue": 10,
  "frequencyCapPeriodType": "DAILY",
  "timezone": "America/Los_Angeles"
}

If budgetSchedules array is not empty, the following campaign object attributes must be set to null or absent in the payload:

  • campaignStartDate
  • campaignEndDate
  • totalBudgetType
  • Budget
  • dailyBudget
  • dailyBudgetType
{
  "name": "test budget4",
  "totalBudgetType": null,
  "budgetSchedules": [
    {
      "scheduleBudget": 0.01,
      "scheduleBudgetType": "DAILY_BUDGET",
      "startDate": "2018-06-18",
      "endDate": "2018-08-18",
      "scheduleName": "schedule1"
    },
    {
      "scheduleBudget": 0.02,
      "scheduleBudgetType": "TOTAL_BUDGET",
      "startDate": "2018-06-28",
      "endDate": "2018-08-30",
      "scheduleName": "schedule2"
    }
  ],
  "goalType": "CTR",
  "goalValue": 0,
  "accountId": 1356341,
  "currency": "USD",
  "status": "ACTIVE",
  "frequencyCapValue": 10,
  "frequencyCapPeriodType": "DAILY",
  "timezone": "America/Los_Angeles"
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "totalBudgetType": "UNLIMITED",
    "dailyBudgetType": "TOTAL_BUDGET",
    "goalType": "CTR",
    "frequencyCapPeriodType": "DAILY",
    "timezone": "America/Los_Angeles",
    "currency": "USD",
    "campaignStartDate": "2018-03-10T08:00:00Z",
    "campaignEndDate": "2018-03-16T07:00:00Z",
    "id": 365122,
    "name": "test budget4",
    "createdAt": "2017-09-22T04:03:42Z",
    "updatedAt": "2017-09-22T04:03:42Z",
    "goalValue": 0,
    "frequencyCapValue": 10,
    "accountId": 1356341,
    "budget": null,
    "dailyBudget": 3
  },
  "errors": null,
  "timeStamp": "2017-09-22T04:03:40Z"
}

Delete Campaign

Campaign deletion is not supported by the API.