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.