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 budgetSchedules array with a single object.

  • Multiple budget schedules apply to the lines under the campaign as defined in the budgetSchedules array with multiple objects.

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.

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

array

Required

Optional

Budget Schedule Object

A Budget Schedule defines a campaign-level budget.

The budgetSchedules array defines one or more Budget Schedule objects. The number of items in the array controls the type of budget schedule. If there is only a single item, the campaign will have a single budget schedule. If there is more than one item, the campaign will have multiple budget schedules. Set up a multi-schedule campaign to manage “evergreen” campaigns that have a single strategy and multiple flight dates and budgets.

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 for multi schedule

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 for multi schedule

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 scheduleDailyBudget 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. Omit or set to null to create an unlimited budget campaign.

string

Required for multi schedule

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/701134

Example Response

{
  "response": {
    "id": 701134,
    "name": "TrafficAPI Single Campaign",
    "createdAt": "2020-08-20T07:52:59Z",
    "updatedAt": "2020-08-20T07:52:59Z",
    "goalValue": 5,
    "frequencyCapValue": 10,
    "accountId": 12034,
    "status": "ACTIVE",
    "goalType": "CTR",
    "timezone": "America/Chicago",
    "currency": "CAD",
    "demoVendor": "COMSCORE",
    "budgetSchedules": [
      {
        "id": 709476,
        "startDate": "2020-08-22T05:00:00Z",
        "endDate": "2020-08-30T05:00:00Z",
        "scheduleBudget": 444.5,
        "scheduleDailyBudget": 18,
        "scheduleBudgetType": "SPECIFIED_AMOUNT"
      }
    ],
    "frequencyCapPeriodType": "DAILY"
  },
  "errors": null,
  "timeStamp": "2020-08-20T07:56:38.729Z"
}

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=2034341&query=traffic+test&page=1&limit=2

Example Response

{
  "response": [
    {
      "id": 735837,
      "name": "traffic test budget 22",
      "createdAt": "2020-09-11T03:01:15Z",
      "updatedAt": "2020-09-11T03:01:15Z",
      "goalValue": 5,
      "frequencyCapValue": 10,
      "accountId": 2034341,
      "status": "ACTIVE",
      "goalType": "CTR",
      "timezone": "America/Chicago",
      "currency": "CAD",
      "demoVendor": "COMSCORE",
      "budgetSchedules": [
        {
          "id": 745083,
          "startDate": "2020-10-27T05:00:00Z",
          "endDate": "2020-10-29T05:00:00Z",
          "scheduleBudget": 22.02,
          "scheduleBudgetType": "TOTAL_BUDGET",
          "scheduleName": "schedule2"
        },
        {
          "id": 745081,
          "startDate": "2020-10-22T05:00:00Z",
          "endDate": "2020-10-26T05:00:00Z",
          "scheduleBudget": 100.01,
          "scheduleDailyBudget": 6.12,
          "scheduleBudgetType": "SPECIFIED_AMOUNT",
          "scheduleName": "schedule1"
        },
        {
          "id": 745082,
          "startDate": "2020-10-30T05:00:00Z",
          "endDate": "2020-11-03T06:00:00Z",
          "scheduleBudget": 140,
          "scheduleBudgetType": "AUTO_ALLOCATED",
          "scheduleName": "schedule3"
        }
      ],
      "frequencyCapPeriodType": "DAILY"
    },
    {
      "id": 735838,
      "name": "traffic test budget - unlimited",
      "createdAt": "2020-09-11T03:03:05Z",
      "updatedAt": "2020-09-11T03:03:05Z",
      "goalValue": 5,
      "frequencyCapValue": 10,
      "accountId": 2034341,
      "status": "ACTIVE",
      "goalType": "CTR",
      "timezone": "America/Chicago",
      "currency": "USD",
      "demoVendor": "COMSCORE",
      "budgetSchedules": [
        {
          "id": 745084,
          "startDate": "2020-08-20T05:00:00Z",
          "endDate": "2020-09-30T05:00:00Z",
          "scheduleDailyBudget": 0,
          "scheduleBudgetType": "TOTAL_BUDGET"
        }
      ],
      "frequencyCapPeriodType": "DAILY"
    }
  ],
  "errors": null,
  "timeStamp": "2020-09-11T03:04:15.399Z"
}

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": "traffic test budget - 24",
  "budgetSchedules": [
    {
      "scheduleBudget": 444.5,
      "scheduleBudgetType": "SPECIFIED_AMOUNT",
      "scheduleDailyBudget": 18,
      "startDate": "2020-08-20",
      "endDate": "2020-09-30"
    }
  ],
  "goalType": "CTR",
  "goalValue": 5,
  "accountId": 2034341,
  "status": "ACTIVE",
  "frequencyCapValue": 10,
  "frequencyCapPeriodType": "DAILY",
  "timezone": "America/Chicago",
  "currency": "USD",
  "demoVendor": "COMSCORE"
}

Example Response

{
  "response": {
    "id": 735839,
    "name": "traffic test budget - 24",
    "createdAt": "2020-09-11T03:06:53Z",
    "updatedAt": "2020-09-11T03:06:53Z",
    "goalValue": 5,
    "frequencyCapValue": 10,
    "accountId": 2034341,
    "status": "ACTIVE",
    "goalType": "CTR",
    "timezone": "America/Chicago",
    "currency": "USD",
    "demoVendor": "COMSCORE",
    "budgetSchedules": [
      {
        "id": 745085,
        "startDate": "2020-08-20T05:00:00Z",
        "endDate": "2020-09-30T05:00:00Z",
        "scheduleBudget": 444.5,
        "scheduleDailyBudget": 18,
        "scheduleBudgetType": "SPECIFIED_AMOUNT"
      }
    ],
    "frequencyCapPeriodType": "DAILY"
  },
  "errors": null,
  "timeStamp": "2020-09-11T03:07:05.730Z"
}

Create Unlimited Budget Campaign

To create a campaign with unlimited budget, omit “scheduleBudget” or alternatively set it to null in the “budgetSchedules” object.

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 (“scheduleBudget” field NULL)

{
  "name": "Test Campaign UNLIMITED",
  "budgetSchedules": [
    {
      "scheduleBudget": null,
      "scheduleBudgetType": "TOTAL_BUDGET",
      "startDate": "2020-08-20",
      "endDate": "2020-08-30"
    }
  ],
  "goalType": "CTR",
  "goalValue": 5,
  "accountId": 2034341,
  "status": "ACTIVE",
  "frequencyCapValue": 10,
  "frequencyCapPeriodType": "DAILY",
  "timezone": "America/Chicago",
  "currency": "USD",
  "demoVendor": "COMSCORE"
}

Example Response

{
  "response": {
    "id": 700866,
    "name": "Test Campaign UNLIMITED",
    "createdAt": "2020-08-19T11:42:55Z",
    "updatedAt": "2020-08-19T11:42:55Z",
    "goalValue": 5,
    "frequencyCapValue": 10,
    "accountId": 2034341,
    "status": "ACTIVE",
    "goalType": "CTR",
    "timezone": "America/Chicago",
    "currency": "USD",
    "demoVendor": "COMSCORE",
    "budgetSchedules": [
      {
        "id": 709200,
        "startDate": "2020-08-20T05:00:00Z",
        "endDate": "2020-08-30T05:00:00Z",
        "scheduleDailyBudget": 0,
        "scheduleBudgetType": "TOTAL_BUDGET"
      }
    ],
    "frequencyCapPeriodType": "DAILY"
  },
  "errors": null,
  "timeStamp": "2020-08-19T11:43:16.007Z"
}

Create a multi schedule budget campaign

To create a multi schedule budget campaign, add multiple flight periods in “budgetSchedules” object.

Example Request Body (Multi Schedule)

{
  "name": "traffic test budget 22",
  "budgetSchedules": [
    {
      "scheduleBudget": 100.01,
      "scheduleBudgetType": "SPECIFIED_AMOUNT",
      "scheduleDailyBudget": 6.12,
      "startDate": "2020-10-22",
      "endDate": "2020-10-26",
      "scheduleName": "schedule1"
    },
    {
      "scheduleBudget": 22.02,
      "scheduleBudgetType": "TOTAL_BUDGET",
      "startDate": "2020-10-27",
      "endDate": "2020-10-29",
      "scheduleName": "schedule2"
    },
    {
      "scheduleBudget": 140,
      "scheduleBudgetType": "AUTO_ALLOCATED",
      "startDate": "2020-10-30",
      "endDate": "2020-11-03",
      "scheduleName": "schedule3"
    }
  ],
  "goalType": "CTR",
  "goalValue": 5,
  "accountId": 2034341,
  "status": "ACTIVE",
  "frequencyCapValue": 10,
  "frequencyCapPeriodType": "DAILY",
  "timezone": "America/Chicago",
  "currency": "CAD",
  "demoVendor": "COMSCORE"
}

Example Response

{
  "response": {
    "id": 735837,
    "name": "traffic test budget 22",
    "createdAt": "2020-09-11T03:01:15Z",
    "updatedAt": "2020-09-11T03:01:15Z",
    "goalValue": 5,
    "frequencyCapValue": 10,
    "accountId": 2034341,
    "status": "ACTIVE",
    "goalType": "CTR",
    "timezone": "America/Chicago",
    "currency": "CAD",
    "demoVendor": "COMSCORE",
    "budgetSchedules": [
      {
        "id": 745083,
        "startDate": "2020-10-27T05:00:00Z",
        "endDate": "2020-10-29T05:00:00Z",
        "scheduleBudget": 22.02,
        "scheduleBudgetType": "TOTAL_BUDGET",
        "scheduleName": "schedule2"
      },
      {
        "id": 745081,
        "startDate": "2020-10-22T05:00:00Z",
        "endDate": "2020-10-26T05:00:00Z",
        "scheduleBudget": 100.01,
        "scheduleDailyBudget": 6.12,
        "scheduleBudgetType": "SPECIFIED_AMOUNT",
        "scheduleName": "schedule1"
      },
      {
        "id": 745082,
        "startDate": "2020-10-30T05:00:00Z",
        "endDate": "2020-11-03T06:00:00Z",
        "scheduleBudget": 140,
        "scheduleBudgetType": "AUTO_ALLOCATED",
        "scheduleName": "schedule3"
      }
    ],
    "frequencyCapPeriodType": "DAILY"
  },
  "errors": null,
  "timeStamp": "2020-09-11T03:01:29.441Z"
}

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/745085

Example Request Body (Single Schedule)

{
  "budgetSchedules": [
    {
      "id": 745085,
      "scheduleBudget": 500,
      "scheduleBudgetType": "SPECIFIED_AMOUNT",
      "scheduleDailyBudget": 18,
      "startDate": "2020-08-20",
      "endDate": "2020-08-30"
    }
  ]
}

Example Request Body (Multi Schedule)

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

Example Response

{
  "response": {
    "id": 735837,
    "name": "traffic test budget 22",
    "createdAt": "2020-09-11T03:01:15Z",
    "updatedAt": "2020-09-11T03:20:33Z",
    "goalValue": 5,
    "frequencyCapValue": 10,
    "accountId": 2034341,
    "status": "ACTIVE",
    "goalType": "CTR",
    "timezone": "America/Chicago",
    "currency": "CAD",
    "demoVendor": "COMSCORE",
    "budgetSchedules": [
      {
        "id": 745083,
        "startDate": "2020-10-27T05:00:00Z",
        "endDate": "2020-10-29T05:00:00Z",
        "scheduleBudget": 22.02,
        "scheduleBudgetType": "TOTAL_BUDGET",
        "scheduleName": "schedule2"
      },
      {
        "id": 745081,
        "startDate": "2020-10-22T05:00:00Z",
        "endDate": "2020-10-26T05:00:00Z",
        "scheduleBudget": 100.01,
        "scheduleDailyBudget": 6.12,
        "scheduleBudgetType": "SPECIFIED_AMOUNT",
        "scheduleName": "schedule1"
      },
      {
        "id": 745082,
        "startDate": "2020-10-30T05:00:00Z",
        "endDate": "2020-11-03T06:00:00Z",
        "scheduleBudget": 140,
        "scheduleBudgetType": "AUTO_ALLOCATED",
        "scheduleName": "schedule3"
      }
    ],
    "frequencyCapPeriodType": "DAILY"
  },
  "errors": null,
  "timeStamp": "2020-09-11T03:21:07.610Z"
}

Switch Single To Multi Schedule Campaign

It is possible to switch an existing single budget schedule to a multiple budget schedule. The existing schedule is needed in the “budgetSchedules” array since the “scheduleName” field is mandatory for multiple schedules. Although more than one schedule may be specified, at least one additional schedule is required for the switch.

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/733216

Example Request Body

{
  "budgetSchedules": [
    {
      "id": 742400,
      "scheduleBudget": 444.5,
      "scheduleBudgetType": "SPECIFIED_AMOUNT",
      "scheduleDailyBudget": 18,
      "startDate": "2020-08-20",
      "endDate": "2020-09-30",
      "scheduleName": "schedule1"
    },
    {
      "scheduleBudget": 22.02,
      "scheduleBudgetType": "TOTAL_BUDGET",
      "startDate": "2020-10-27",
      "endDate": "2020-10-29",
      "scheduleName": "schedule2"
    },
    {
      "scheduleBudget": 140,
      "scheduleBudgetType": "AUTO_ALLOCATED",
      "startDate": "2020-10-30",
      "endDate": "2020-11-03",
      "scheduleName": "schedule3"
    }
  ]
}

Example Response

{
  "response": {
    "id": 733216,
    "name": "test budget 7001",
    "createdAt": "2020-09-10T15:57:07Z",
    "updatedAt": "2020-09-11T03:38:51Z",
    "goalValue": 5,
    "frequencyCapValue": 10,
    "accountId": 1,
    "status": "ACTIVE",
    "goalType": "CTR",
    "timezone": "America/Chicago",
    "currency": "USD",
    "demoVendor": "COMSCORE",
    "budgetSchedules": [
      {
        "id": 745087,
        "startDate": "2020-10-27T05:00:00Z",
        "endDate": "2020-10-29T05:00:00Z",
        "scheduleBudget": 22.02,
        "scheduleBudgetType": "TOTAL_BUDGET",
        "scheduleName": "schedule2"
      },
      {
        "id": 745086,
        "startDate": "2020-10-30T05:00:00Z",
        "endDate": "2020-11-03T06:00:00Z",
        "scheduleBudget": 140,
        "scheduleBudgetType": "AUTO_ALLOCATED",
        "scheduleName": "schedule3"
      },
      {
        "id": 742400,
        "startDate": "2020-08-20T05:00:00Z",
        "endDate": "2020-09-30T05:00:00Z",
        "scheduleBudget": 444.5,
        "scheduleDailyBudget": 18,
        "scheduleBudgetType": "SPECIFIED_AMOUNT",
        "scheduleName": "schedule1"
      }
    ],
    "frequencyCapPeriodType": "DAILY"
  },
  "errors": null,
  "timeStamp": "2020-09-11T03:39:24.850Z"
}

Delete Campaign

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