Campaigns

This article describes services you can use to view, add, and update campaigns.

Overview

A campaign is an advertising goal that defines a strategy for delivering ads within a set time period. You set up a campaign by defining its flight dates, budgets, frequency caps, demographic targeting data provider, and campaign goals.

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

You can set one of the following campaign budget types:

  • 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 apply to the lines under the campaign as defined in the budgetSchedules array.

Hierarchy

A Campaign is an advertiser-level object.

Endpoint

/traffic/campaigns

Use the following HTTP methods:

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

Resources

Campaign

The Campaign object contains the following fields:

Field Description Data Type Create Update
id Specifies the campaign ID. integer N/A Required
name Specifies the unique campaign name. 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: The total budget has been reached.
  • STOP_DAILY_BUDGET: The daily budget has been reached.
  • NOT_STARTED: The campaign has not started.
  • ENDED: The campaign has ended.
  • NO_ADS_ADDED: The campaign has no ads associated with it.
  • ERROR: An error occurred.
string Required Optional
goalType

Specifies the campaign KPI. Options include:

  • CTR
  • CPC
  • CPA
  • CPCV
  • VCPM
  • ROAS
  • CPI
string Required Optional
goalValue

Specifies 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: Set frequency capping at the line level for each line.
  • MINUTES: Defines campaign frequency capping to the minute.
  • HOURLY: Defines campaign frequency capping hourly.
  • DAILY: Defines campaign frequency capping daily.
  • WEEKLY: Defines campaign frequency capping weekly.
  • MONTHLY: Defines campaign frequency capping monthly.

Defaults to UNLIMITED if you don’t specify a value.

string Optional Optional
frequencyCapValue

Specifies the maximum number of impressions to serve per frequencyCapPeriodType.

Defaults to 0 if you don’t specify a value.

number Optional Optional
demoVendor

Specifies the demographic targeting data provider for video campaigns.

The Verizon Media 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: You cannot change this value on an active campaign.

Defaults to YAHOO if you don’t specify a value.

string Optional Optional
timezone

Specifies the campaign time zone.

Uses the advertiser’s time zone if you do not specify a value. To learn more, see Timezones. Some example values: America/New_York, Etc/GMT.

Note: Once a campaign is saved, you cannot update the timezone value.

string Optional Optional
currency

Specifies the campaign currency.

Uses the advertiser’s currency if you do not specify a value. To learn more, see Currency Types. Some example values: USD, CAD.

Note: Once a campaign is saved, you cannot update the currency.

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 you can use when you set up lines under the campaign. To learn more, see Budget Schedule Object.

Once you set up budget schedules, you cannot remove them from a campaign. Budget schedule date ranges cannot overlap.

array Optional Optional
dailyBudgetType

Specifies the daily budget type. Options include:

  • TOTAL_BUDGET: The entire campaign budget is available.
  • SPECIFIED_AMOUNT: You define a daily spending cap using the dailyBudget field.
  • AUTO_ALLOCATED: Verizon Media DSP automatically allocates the remaining budget at a regular rate for the remainder of the campaign.

Important: If you define the budgetSchedules array, Verizon Media DSP ignores the value in this field.

Defaults to TOTAL_BUDGET if you don’t specify a value.

string Optional Optional
dailyBudget

Specifies the daily budget.

Important: If you define the budgetSchedules array, Verizon Media DSP ignores the value in this field.

Required if dailyBudgetType is SPECIFIED_AMOUNT.

number Optional Optional
totalBudgetType

Specifies the total budget type. Options include:

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

Important: If you define the budgetSchedules array, Verizon Media DSP ignores the value in this field.

Defaults to UNLIMITED if you don’t specify a value.

string Optional Optional
budget

Specifies the total budget for the campaign.

Important: If you define the budgetSchedules array, Verizon Media DSP ignores the value in this field.

Required if the totalBudgetType is SPECIFIED_AMOUNT.

number Optional Optional
campaignStartDate

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

Important: If you define the budgetSchedules array, Verizon Media DSP ignores the value in this field.

Note: The start time depends on the campaign’s time zone.

Required if a single budget is defined for the campaign.

string Optional Optional
campaignEndDate

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

Important: If you define the budgetSchedules array, Verizon Media DSP ignores the value in this field.

string Optional Optional

Budget Schedule Object

A Budget Schedule is a campaign-level budget you can define. Budget schedules are useful if you want to run evergreen lines instead of having to continually define new lines every time your lines end.

The campaign object’s budgetSchedules array defines one or more Budget Schedule objects.

If you specify the budgetSchdule object attributes, omit the campaign object’s dailyBudget, dailyBudgetType, totalBudgetType, and budget attributes; or set them to null.

Important

Once you specify budget schedules, you cannot remove them from a campaign. Budget schedule date ranges cannot overlap.

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 budget schedule in yyyy-MM-dd format. string Required Required
endDate Specifies the ending of the budget schedule in yyyy-MM-dd format. string Required Required
scheduleBudgetType

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

  • TOTAL_BUDGET: The entire campaign budget is available.
  • SPECIFIED_AMOUNT: You can define a daily spending cap in the dailyBudget parameter.
  • AUTO_ALLOCATED: Verizon Media DSP automatically allocates the remaining budget at a regular rate for the rest of the budget schedule.
string Required Required
scheduleBudget Specifies the total budget for the budget schedule. string Required Optional
scheduleDailyBudget

Specifies the daily budget for the budget schedule.

Required if the scheduleBudgetType is SPECIFIED_AMOUNT.

string Optional Optional

View Campaign

Get data for a specific campaign.

GET /traffic/campaigns/{id}

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"
}

View Campaigns

Get a filtered list of campaigns.

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

All of the following parameters are query parameters.

Parameters

Parameter Description Data Type Required
accountId Specifies the advertiser ID. integer Y
query

Specifies the search term to use for filtering an advertiser’s campaigns.

Use URL encoding conventions (i.e. replace spaces with a + or %20).

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

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"
}

Create Campaign

Create a new campaign.

POST /traffic/campaigns

Parameters

All fields 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"
}

Update Campaign

Update an existing campaign.

PUT /traffic/campaigns/{id}

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

Parameters

Specify the Campaign id in the url path. Specify all other fields 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"
}

Delete Campaign

The DSP Traffic API does not support the deletion of campaigns.