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

/traffic/campaigns

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

  • Use the GET method to read an existing campaign.
  • Use the POST method to create a new campaign.
  • Use the PUT method to update an existing campaign.

Resources

Campaign Object

The Campaign object contains the following fields:

Table 74 Campaign Fields
Field Description Data Type Create Update
id Specifies the campaign ID. integer N/A Required
name Specifies the unique name of the campaign. string Required Optional
status

Specifies the current status of the campaign.

Allowed values:

  • ACTIVE
  • PAUSED
  • INACTIVE

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

  • 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 Required Optional
goalType

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

  • CTR
  • CPC
  • CPA
  • CPCV
  • VCPM
  • ROAS
  • CPI
string Required Optional
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 Required Optional
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.
[1]If not specified when creating a Campaign, defaults to UNLIMITED.
string Optional [1] Optional
frequencyCapValue

Specifies the maximum number of impressions to serve per the frequencyCapPeriodType.

[2]If not specified when creating a Campaign, defaults to 0.
number Optional [2] Optional
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: This value can not be changed on an active campaign.

[3]If not specified when creating a Campaign, defaults to YAHOO.
string Optional [3] Optional
timezone

Specifies the time zone of the campaign.

If undefined or set to null, the advertiser’s timezone is used. To learn more, see Timezones. Some example values: America/New_York, Etc/GMT.

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

string Optional Optional
currency

Specifies the currency of the campaign.

If undefined or set to null, the advertiser’s currency is used. To learn more, see Currency Types. Some example values: USD, CAD.

Note: Once a campaign is saved, the currency value cannot be updated.

string Optional Optional
accountId

Specifies the advertiser ID.

To learn more, see Advertisers.

integer Required Optional
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.

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

array Optional Optional
dailyBudgetType

Specifies the daily budget type. Options include:

  • TOTAL_BUDGET: 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.

Important: If the budgetSchedules array is defined, the value of this field is ignored.

[4]If not specified when creating a Campaign, defaults to TOTAL_BUDGET.
string Optional [4] Optional
dailyBudget

Specifies the daily budget.

Important: If the budgetSchedules array is defined, the value of this field is ignored.

[5]Required if dailyBudgetType is SPECIFIED_AMOUNT.
number Optional [5] Optional
totalBudgetType

Specifies the total budget type. Options include:

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

Important: If the budgetSchedules array is defined, the value of this field is ignored.

[6]If not specified when creating a Campaign, defaults to UNLIMITED.
string Optional [6] Optional
budget

Specifies the total budget for the campaign.

Important: If the budgetSchedules array is defined, the value of this field is ignored.

[7]Required if the totalBudgetType is SPECIFIED_AMOUNT
number Optional [7] Optional
campaignStartDate

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

Important: If the budgetSchedules array is defined, the value of this field is ignored.

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

[8]Required if a single budget is defined for the campaign.
string Optional [8] Optional
campaignEndDate

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

Important: If the budgetSchedules array is defined, the value of this field is ignored.

string Optional Optional

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.

If the budgetSchdule object attributes are specified, the corresponding campaign object attributes must be omitted or 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 75 Budget Schedule Fields
Field Description Data Type Create Update
id Specifies the budget schedule ID. integer N/A Required
scheduleName Specifies a unique name for the budget schedule. string Required Optional
startDate Specifies the beginning of the campaign in yyyy-MM-dd format. string Required Required
endDate Specifies the ending of the campaign in yyyy-MM-dd format. string Required Required
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.
string Required Required
scheduleBudget Specifies the total budget for the budget schedule. string Required Optional
scheduleDailyBudget

Specifies the daily budget amount.

[9]Required if the scheduleBudgetType is SPECIFIED_AMOUNT.
string Optional [9] Optional

Read Campaign

Get data for a specific campaign.

GET /traffic/campaigns/{id}

Parameters

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

Example Request URL

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

Example Response

{
  "response": {
    "status": "NOT_STARTED",
    "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-28T23:01:34Z",
    "goalValue": 0,
    "frequencyCapValue": 10,
    "accountId": 1356341,
    "budget": 7440.7,
    "dailyBudget": 3
  },
  "errors": null,
  "timeStamp": "2018-12-20T17:42:56Z"
}

Read Campaigns

Get a filtered list of campaigns.

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

Parameters

Table 77 Read Campaigns Parameters
Parameter Parameter Type Description Data Type Required
accountId query Specifies the advertiser ID. integer Y
query query

Specifies the search term.

Use URL encoding conventions (i.e. a space should be replaced with a + or %20).

string N
page query Specifies the page number. integer N
limit query Specifies the total number of items to return. Maximum allowed value is 100. integer N
sort query Specifies the column to sort by. string N
dir query

Specifies the sort direction. Allowed values:

  • ASC: data is sorted in ascending order.
  • DESC: data is sorted in decending order.
string N

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/campaigns?accountId=1356341&query=test&page=1&limit=2

Example Response

{
  "response": [
    {
      "status": "INACTIVE",
      "totalBudgetType": "SPECIFIED_AMOUNT",
      "dailyBudgetType": "TOTAL_BUDGET",
      "goalType": "CTR",
      "frequencyCapPeriodType": "UNLIMITED",
      "timezone": "America/New_York",
      "currency": "CHF",
      "demoVendor": "YAHOO",
      "campaignStartDate": "2017-06-28T04:00:00Z",
      "id": 319128,
      "name": "testBudget",
      "createdAt": "2017-06-27T17:43:44Z",
      "updatedAt": "2017-06-27T17:43:44Z",
      "goalValue": 0,
      "frequencyCapValue": 0,
      "accountId": 311375,
      "budget": 2
    },
    {
      "status": "INACTIVE",
      "goalType": "CTR",
      "frequencyCapPeriodType": "UNLIMITED",
      "timezone": "America/Los_Angeles",
      "currency": "USD",
      "demoVendor": "YAHOO",
      "budgetSchedules": [
        {
          "scheduleBudget": 100.01,
          "scheduleDailyBudget": 6.12,
          "scheduleBudgetType": "SPECIFIED_AMOUNT",
          "scheduleName": "schedule1",
          "startDate": "2018-12-22T08:00:00Z",
          "endDate": "2018-12-27T08:00:00Z",
          "id": 695833
        },
        {
          "scheduleBudget": 22.02,
          "scheduleBudgetType": "TOTAL_BUDGET",
          "scheduleName": "schedule2",
          "startDate": "2018-12-28T08:00:00Z",
          "endDate": "2018-12-30T08:00:00Z",
          "id": 695834
        },
        {
          "scheduleBudget": 140,
          "scheduleBudgetType": "AUTO_ALLOCATED",
          "scheduleName": "schedule3",
          "startDate": "2019-01-01T08:00:00Z",
          "endDate": "2019-01-05T08:00:00Z",
          "id": 695835
        }
      ],
      "id": 661249,
      "name": "multiple budget schedule test",
      "createdAt": "2018-10-19T18:31:28Z",
      "updatedAt": "2018-12-19T20:19:27Z",
      "goalValue": 0,
      "frequencyCapValue": 0,
      "accountId": 311375,
      "budget": null
    }
  ],
  "errors": null,
  "timeStamp": "2018-12-19T20:19:57Z"
}

Update Campaign

Update an existing campaign.

PUT /traffic/campaigns/{id}

Partial updates are supported; values of supported fields which are not in the payload will remain unchanged.

Parameters

The Campaign id is specified in the url path. All other fields are specified in the body of the application/json payload.

Example Request URL

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

Example Request Body (Single Schedule)

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

Example Request Body (Multi Schedule)

{
  "budgetSchedules": [
    {
      "scheduleBudget": 140.01,
      "scheduleDailyBudget": 6.55,
      "scheduleBudgetType": "SPECIFIED_AMOUNT",
      "scheduleName": "schedule1-updated",
      "startDate": "2018-12-22",
      "endDate": "2018-12-27",
      "id": 695833
    }
  ]
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "goalType": "CTR",
    "frequencyCapPeriodType": "DAILY",
    "timezone": "America/Los_Angeles",
    "currency": "USD",
    "demoVendor": "YAHOO",
    "budgetSchedules": [
      {
        "scheduleBudget": 22.02,
        "scheduleBudgetType": "TOTAL_BUDGET",
        "scheduleName": "schedule2",
        "startDate": "2018-12-28T08:00:00Z",
        "endDate": "2018-12-30T08:00:00Z",
        "id": 695834
      },
      {
        "scheduleBudget": 140,
        "scheduleBudgetType": "AUTO_ALLOCATED",
        "scheduleName": "schedule3",
        "startDate": "2019-01-01T08:00:00Z",
        "endDate": "2019-01-05T08:00:00Z",
        "id": 695835
      },
      {
        "scheduleBudget": 140.01,
        "scheduleDailyBudget": 6.55,
        "scheduleBudgetType": "SPECIFIED_AMOUNT",
        "scheduleName": "schedule1-updated",
        "startDate": "2018-12-22T08:00:00Z",
        "endDate": "2018-12-27T08:00:00Z",
        "id": 695833
      }
    ],
    "id": 696153,
    "name": "test budget 56747",
    "createdAt": "2018-12-20T02:36:59Z",
    "updatedAt": "2018-12-20T17:53:12Z",
    "goalValue": 0,
    "frequencyCapValue": 10,
    "accountId": 1356341,
    "budget": null
  },
  "errors": null,
  "timeStamp": "2018-12-20T17:53:13Z"
}

Create Campaign

Create a new campaign.

POST /traffic/campaigns

Parameters

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

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/campaigns

Example Request Body (Single Schedule)

{
  "name": "test budget 4",
  "campaignStartDate": "2018-12-24",
  "campaignEndDate": "2018-12-27",
  "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"
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "totalBudgetType": "UNLIMITED",
    "dailyBudgetType": "TOTAL_BUDGET",
    "goalType": "CTR",
    "frequencyCapPeriodType": "DAILY",
    "timezone": "America/Los_Angeles",
    "currency": "USD",
    "demoVendor": "YAHOO",
    "campaignStartDate": "2018-12-24T08:00:00Z",
    "campaignEndDate": "2018-12-27T08:00:00Z",
    "id": 696162,
    "name": "test budget 4",
    "createdAt": "2018-12-20T18:22:16Z",
    "updatedAt": "2018-12-20T18:22:16Z",
    "goalValue": 0,
    "frequencyCapValue": 10,
    "accountId": 1356341,
    "budget": null,
    "dailyBudget": 3
  },
  "errors": null,
  "timeStamp": "2018-12-20T18:22:16Z"
}

Example Request Body (Multi Schedule)

{
  "name": "test budget 22",
  "campaignStartDate": "2018-12-24",
  "budgetSchedules": [
    {
      "scheduleBudget": 100.01,
      "scheduleBudgetType": "SPECIFIED_AMOUNT",
      "scheduleDailyBudget": 6.12,
      "startDate": "2018-12-22",
      "endDate": "2019-02-26",
      "scheduleName": "schedule1"
    },
    {
      "scheduleBudget": 22.02,
      "scheduleBudgetType": "TOTAL_BUDGET",
      "startDate": "2019-02-27",
      "endDate": "2019-02-28",
      "scheduleName": "schedule2"
    },
    {
      "scheduleBudget": 140,
      "scheduleBudgetType": "AUTO_ALLOCATED",
      "startDate": "2019-03-01",
      "endDate": "2019-03-05",
      "scheduleName": "schedule3"
    }
  ],
  "goalType": "CTR",
  "goalValue": 5,
  "accountId": 1356341,
  "status": "ACTIVE",
  "frequencyCapValue": 10,
  "frequencyCapPeriodType": "DAILY",
  "timezone": "America/Chicago",
  "currency": "CAD",
  "demoVendor": "COMSCORE",
  "budget": 432.6
}

Example Response

{
  "response": {
    "id": 748390,
    "name": "test budget 22",
    "createdAt": "2019-02-16T00:45:15Z",
    "updatedAt": "2019-02-16T00:45:15Z",
    "goalValue": 5,
    "frequencyCapValue": 10,
    "accountId": 1356341,
    "status": "ACTIVE",
    "goalType": "CTR",
    "timezone": "America/Chicago",
    "currency": "CAD",
    "demoVendor": "COMSCORE",
    "budgetSchedules": [
      {
        "id": 749323,
        "startDate": "2018-12-22T06:00:00Z",
        "endDate": "2019-02-26T06:00:00Z",
        "scheduleBudget": 100.01,
        "scheduleDailyBudget": 6.12,
        "scheduleBudgetType": "SPECIFIED_AMOUNT",
        "scheduleName": "schedule1"
      },
      {
        "id": 749325,
        "startDate": "2019-03-01T06:00:00Z",
        "endDate": "2019-03-05T06:00:00Z",
        "scheduleBudget": 140,
        "scheduleBudgetType": "AUTO_ALLOCATED",
        "scheduleName": "schedule3"
      },
      {
        "id": 749324,
        "startDate": "2019-02-27T06:00:00Z",
        "endDate": "2019-02-28T06:00:00Z",
        "scheduleBudget": 22.02,
        "scheduleBudgetType": "TOTAL_BUDGET",
        "scheduleName": "schedule2"
      }
    ],
    "frequencyCapPeriodType": "DAILY"
  },
  "errors": null,
  "timeStamp": "2019-02-16T00:45:19.783Z"
}

Delete Campaign

The DSP Traffic API does not support deletion of campaigns.