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.