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/Verizon Media 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

Read Campaign

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

Read Campaigns

Read a filtered list of campaigns.

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

All of the accepted 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",
  "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.