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 82 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
  • CPI
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: [1] 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 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: This value can not be changed on an active campaign.

string N N
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 N N
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 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 budgetSchedules array is defined and not empty, 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 N
dailyBudgetType

Specifies the daily budget type. Options include:

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

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

Specifies the daily budget.

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

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

Specifies the total budget type. Options include:

  • UNLIMITED: [4] 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.

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

[4]If not specified when creating a Campaign, defaults to UNLIMITED.
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.

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

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

[6]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 [6] 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.

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 83 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 omitted or set to null.

string Y Y
endDate

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

If specified, the campaign object’s campaignEndDate must be omitted or set to null.

string Y Y
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 omitted or set to null.

string Y Y
scheduleBudget Specifies the total budget for the budget schedule. string Y N
scheduleDailyBudget

Specifies the daily budget amount.

[7]Required if the scheduleBudgetType is SPECIFIED_AMOUNT.
string N [7] 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 84 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": "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 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 85 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

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 Campaigns

Updates an existing campaign.

PUT /traffic/campaigns/{id}

The response returns the updated campaign.

Example Request

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

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
{
  "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 Campaigns

Creates a new campaign.

POST /traffic/campaigns

The response returns a newly created campaign.

Example Request (Single Schedule)

No parameters are specified in the URL path.

POST /traffic/campaigns

All parameters are defined in the application/json payload.

{
  "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 (Multi Schedule)

No parameters are specified in the URL path.

POST /traffic/campaigns

All parameters are defined in the application/json payload.

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 budget 50",
  "totalBudgetType": null,
  "dailyBudgetType": null,
  "budgetSchedules": [
    {
      "scheduleBudget": 100.01,
      "scheduleBudgetType": "SPECIFIED_AMOUNT",
      "scheduleDailyBudget": 6.12,
      "startDate": "2018-12-22",
      "endDate": "2018-12-27",
      "scheduleName": "schedule1"
    },
    {
      "scheduleBudget": 22.02,
      "scheduleBudgetType": "TOTAL_BUDGET",
      "startDate": "2018-12-28",
      "endDate": "2018-12-30",
      "scheduleName": "schedule2"
    },
    {
      "scheduleBudget": 140,
      "scheduleBudgetType": "AUTO_ALLOCATED",
      "startDate": "2019-01-01",
      "endDate": "2019-01-05",
      "scheduleName": "schedule3"
    }
  ],
  "goalType": "CTR",
  "goalValue": 0,
  "accountId": 1356341,
  "currency": "USD",
  "status": "ACTIVE",
  "frequencyCapValue": 10,
  "frequencyCapPeriodType": "DAILY",
  "timezone": "America/Los_Angeles"
}

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": 695852
      },
      {
        "scheduleBudget": 140,
        "scheduleBudgetType": "AUTO_ALLOCATED",
        "scheduleName": "schedule3",
        "startDate": "2019-01-01T08:00:00Z",
        "endDate": "2019-01-05T08:00:00Z",
        "id": 695853
      },
      {
        "scheduleBudget": 100.01,
        "scheduleDailyBudget": 6.12,
        "scheduleBudgetType": "SPECIFIED_AMOUNT",
        "scheduleName": "schedule1",
        "startDate": "2018-12-22T08:00:00Z",
        "endDate": "2018-12-27T08:00:00Z",
        "id": 695851
      }
    ],
    "id": 696169,
    "name": "test budget 50",
    "createdAt": "2018-12-20T20:21:08Z",
    "updatedAt": "2018-12-20T20:21:08Z",
    "goalValue": 0,
    "frequencyCapValue": 10,
    "accountId": 1356341,
    "budget": null
  },
  "errors": null,
  "timeStamp": "2018-12-20T20:21:08Z"
}

Delete Campaign

Campaign deletion is not supported by the API.