Lines

Line budgets, bidding, and billing are tied together in support of a line goal. The line optimizes bidding towards an objective. But line goals are always always constrained by media, budget, and billing configurations that define that line.

Overview

In Oath Ad Platforms DSP, a line is subcomponent of a campaign that specifies an advertising strategy. Every line is defined by one or more ads, a goal type, and a set of budgetary and targeting parameters.

As a best practice, each line item should represent a distinct targeting strategy. Using lines, a campaign can independently target diverse exchanges, deals, locations, demographics, ad positions, frequency, audiences, devices, days of the week, apps, URLs, page relevancy, mobile carriers, and languages.

Although budgets and targeting can be specified at both the campaign and line level, flight dates, frequency caps, and budgets specified at the campaign level override line-level configurations.

Endpoint

You can use this endpoint to read, create, and update line objects.

https://dspapi.admanagerplus.yahoo.com/traffic/lines

The action taken depends on the HTTP method and the parameters specified.

  • Use the GET method to read existing lines.
  • Use the POST method to add new lines.
  • Use the PUT method to update existing lines.

Resources

The platform provides the following resources for managing and tracking lines:

  • lines
  • budgetSchedule
  • lineFees
  • conversions

Lines

The lines resource contains the following fields:

Table 112 Lines Resource
Field Description Data Type Add Update
id Specifies the line ID. integer N/A Required
name Specifies the unique name of the line. string Required Optional
orderId

Specifies the campaign ID.

To learn more, see Campaigns.

integer Required Optional
mediaType

Specifies the the media type served by the line.

  • DISPLAY: To run an image ad, create a display line item within a campaign.
  • VIDEO: To run a video ad, create a video line item within a campaign.
  • AUDIO: To run a audio ad, create an audio line item within a campaign.
string Required Optional
status

Specifies the current status of the line.

  • ACTIVE: Active/running
  • PAUSED: Just ended
  • INACTIVE: Inactive/ended

The following status types are read-only:

  • STOP_TOTAL_BUDGET: Total budget reached
  • STOP_DAILY_BUDGET: Daily budget reached
  • NOT_STARTED: Not started yet
  • ENDED: Ended
  • ERROR: Error
string Required Optional
goalType

Specifies the goal type the platform will use to optimize line performance.

Different goal types are available depending on the mediaType value specified.

Display Line

  • NONE: This is the default option. With this goal type, Oath Ad Platforms DSP does not factor in a goal when it bids on impressions.
  • CPC: Establish a cost per click goal by specifying the target CPC (goalAmount) and Max CPM (bidPrice) amounts.
  • CPA: Establish a cost per action goal by specifying the Target CPA (goalAmount) and Max CPM (bidPrice) amounts.
  • VCPM: Establish a viewable CPM goal by specifying the target VCPM (goalAmount) and Max CPM (bidPrice) amounts.
  • ROAS: Establish a return on ad spend goal by specifying the Max ROAS (maxGoal) and Max CPM (bidPrice) amounts.
  • MAXINVIEWRATE: Maximize Viewability: Establish a soft goal to maximize viewability by specifying the Max CPM (bidPrice) amount.
  • OCPC: (Fixed CPM billing only, i.e. when billingMethodType is CPM_PRICE) Establish an optimized CPC goal by specifying the target CPC (goalAmount) and profit margin percentage (marginGoal).

Video Line

  • NONE: This is the default option. With this goal type, Oath Ad Platforms DSP does not factor in a goal when it bids on impressions.

  • CPC: Establish a cost per click goal by specifying the target CPC (goalAmount) and Max CPM (bidPrice) amounts.

  • CPCV: Establish a cost per single completed view goal by specifying the Target CPCV (goalAmount), Max CPM (bidPrice) amounts. When billingMethodType is CPM_PRICE, additionally specify Max CPCV (maxGoal) amount.

  • VCPM: Establish a viewable CPM goal for oCPM and Fixed CPM-billed lines by specifying the target VCPM (goalAmount) and Max CPM (bidPrice) amounts.

  • MAXCOMPLETIONRATE: Maximize Completion Rate: This is a soft optimization feature that helps improve the video completion rate over time without sacrificing impression delivery. For this goal type, specify the CPM (bidPrice) amount.

  • MAXCTR: Maximize CTR: This is a soft optimization feature that helps improve the click-through rate (CTR) over time without sacrificing impression delivery. For this goal type, specify the CPM (bidPrice) amount.

  • MAXINVIEWRATE: Maximize Viewability: This is a soft optimization feature that helps improve the video viewability as defined by third-party measurement provider Moat.

    A viewable video impression requires that 50% of video ad pixels are active and in the viewable portion of the viewer’s browser for two consecutive seconds. For this goal type, specify the CPM (bidPrice) amount.

  • COMPLETION_HARD_THRESHOLD: Specify Max CPM (bidPrice) amount and the completionThreshold percentage. (This goal type requires special role).

Audio Line

  • NONE: This is the default option. With this goal type, BrightRoll DSP does not factor in a goal when it bids on impressions.
  • ECPM: Establish a CPM goal by specifying the target ECPM (goalAmount) and Max ECPM (bidPrice) amounts.
string Required Optional
goalAmount Specifies the target amount for certain goal types. number Required Optional
bidPrice Specifies the maximum bid price (Maximum CPM Price) allowed for certain goal types. number Required Required
maxGoal Specifies the maximum goal price. Required if the goalType is ROAS or CPCV. number Required Optional
marginGoal

Specifies the margin percentage.

[1]Required when goalType is OCPC.
number Required [1] Optional
isNativeEnabled

Specifies if the line can serve native ads. Native ads are not supported at this time for video lines.

  • If true, enable native ad support.
  • If false, disables native ad support; the default settng.

Important: Once the line is created, this value cannot be changed.

boolean Optional Optional
pacingModeType

Specifies the pacing mode.

  • EVEN: Spread the line budget evenly. If your daily budget is Auto Allocated, Oath Ad Platforms DSP spreads the total budget evenly over the line’s flight dates. If your daily budget is a Specified Amount, Oath Ad Platforms DSP spreads the specified daily budget evenly throughout the day.
  • ASAP: Bid on every impression opportunity that meets the line’s targeting criteria. If your daily budget is Auto Allocated, Oath Ad Platforms DSP delivers ASAP until all remaining budget is consumed. If your daily budget is a Specified Amount, Oath Ad Platforms DSP delivers ASAP until the specified amount is consumed.
  • AHEAD: Provides greater control over how line budgets are allocated during a flight by enabling you to over-pace daily budgets. If the daily budget is user-specified, the line will over-pace the daily budget every day until the total budget is consumed. The amount over-spent is determined by the pacingAcceleration specified. If the line’s daily budget is auto-allocated, the line’s spend rate is dynamically determined based on the line’s remaining total budget, the remaining days in the flight, and the line’s pacingAcceleration.
string Required Optional
pacingAcceleration

Specifies the percentage over the daily budget that the line may spend per day.

Ahead pacing is the product of the even pacing value multiplied by the pacing acceleration value: (remaining budget/remaining days) * pacing acceleration value.

[2]Required if the value of pacingModeType is AHEAD.
number Required [2] Optional
budgetType

Specifies whether the line uses impression-based budgeting or budgeting based on US dollars for the line.

  • CURRENCY: Budget based on US Dollars.
  • IMPRESSION: Budget based on impressions. Impression-based budgeting enables you to control the number of impressions a line delivers, and respects the line’s Max CPM price, daily pacing, optimization goals, and targeting options.
string Required Optional
dailyBudgetType

Specifies the daily budget type is used to indicate how the line’s budget is allocated.

  • SPECIFIED_AMOUNT: Specify a daily spend cap for the line in the dailyBudget field.
  • AUTO_ALLOCATED: Allocation based on the overall budget and the number of days left in the line’s flight.
string Optional Optional
dailyBudget

Specifies the daily budget amount.

[3]Required if the budgetType is CURRENCY and dailyBudgetType is SPECIFIED_AMOUNT.
number Required [3] Optional
impBudget

Specifies the total number of impressions bought.

[4]Required when budgetType is IMPRESSION.
integer Required [4] Optional
impDailyBudget

Specifies the total number of impressions bought per day.

[5]Required when budgetType is IMPRESSION.
impression Required [5] Optional
billingMethodType

Specifies the billing method.

  • CPM_PRICE: With Fixed CPM billing, you pay a fixed price per thousand impressions.
  • CPC: With Fixed CPC billing, you pay a fixed price per click.
  • MARGIN: (oCPM) With oCPM billing, Oath Ad Platforms DSP predicts the probability that events (such as clicks, conversions, video completions, or impressions) will occur.
  • CPCV: (Video Line only) Cost Per Completed View for video. With CPCV billing, you only pay for completed video views. Note: If you choose CPCV, you must set pacingMode to EVEN and you can only set goalType to either CPCV or NONE.
string Required Optional
billingPrice

Specifies the amount paid based on the specified billingMethodType.

  • When billingMethodType is MARGIN (oCPM), specifies the profit margin percentage.
  • When billingMethodType is CPCV, this field represents the amount you want to pay for each completed video view.
  • When billingMethodType is CPM_PRICE, this field represents the amount you want to pay per thousand impressions.
  • When billingMethodType is CPC, this field represents the amount you want to pay for each click.
number Optional Optional
marginType

Specifies how the margin is calculated.

  • TOTAL_BUDGET: Margin is calculated as a percentage of advertiser spend, which includes all costs (inventory, Yahoo fees, and variable costs).
  • BUYER_COST: Margin is calculated as a percentage of the buyer cost where buyer cost = inventory cost + Oath fees. This option excludes all variable costs.

Note: This is available to self-serve accounts only.

string Optional Optional
completionThreshold

Specifies the completion threshold percentage.

[6]Required when goalType is COMPLETION_HARD_THRESHOLD.
integer Required [6] Optional
budgetSchedule

Specifies the line’s budget schedule.

To learn more, see Budget Schedule.

object Required Optional
lineFees

Track external costs such as ad serving, measurement, and brand safety costs. To help you better manage your margins, you can add up to six variable CPM costs to each line for tracking purposes.

To learn more, see Line Fees.

Note: This is available to self-serve accounts only.

object Optional Optional
conversions

Oath Ad Platforms DSP can optimize a line with multiple conversion rules when you establish conversion values.

To learn more, see Conversions Object.

object Optional Optional

Budget Schedule

The budgetSchedule object contains the following fields:

Table 113 Update Lines
Name Description Data Type Add Update
id Specifies the budget schedule ID. integer N/A N/A
startDateStr Specifies the start date of the line in the yyyy-MM-dd format. string Required Required
endDateStr Specifies the end date of the line in the yyyy-MM-dd format. string Required Required
budget Specifies the total budget of the line. number Required Optional

Line Fees

Note

This feature is only available for self-serve accounts.

The lineFees object contains the following fields:

Table 114 Line Fees Resource
Name Description Data Type Add Update
id Specifies the ID. integer N/A N/A
name Specifies a user-defined name. string Required Required
fee Specifies the CPM amount: the amount you must pay per thousand impressions. number Required Optional
typeName

Specifies the variable cost type.

  • AD_SERVING: Track external ad serving cost.
  • AD_VERIFICATION: Track external ad verification cost.
  • AUDIENCE_MEASUREMENT: Track external ad measurement cost.
  • BRAND_SAFETY: Track external brand safety cost.
  • VIEWABILITY: Track external viewability cost.
  • OTHER_FEE: Any additional external cost.

Note: Once a variable cost is created, it’s type cannot be changed.

string Required N/A

Conversions Object

Oath Ad Platforms DSP can optimize a line with multiple conversion rules when you establish conversion values.

To obtain the available conversions, see Read Advertiser Beacon Lookups.

The conversions object contains the following fields:

Table 115 Conversions Object
Parameter Description Data Type Add Update
id Specifies the line ID. integer N/A N/A
name Specifies the name of the conversion pixel. integer Required Required
beaconId Specifies the conversion pixel ID. integer Required Required
acceptViewThrough Specifies whether a view through is accepted. boolean Required Optional
clickWindow Specifies the amount of time after a click that the conversion is tracked. integer Required Required
clickWindowUnit

Specifies the click window unit type.

  • DAY: If specified, clickWindow can have minimum value of 1 and maximum value of 45.
  • HOUR: If specified, clickWindow can have minimum value of 1 and maximum value of 48.
  • MINUTE: If specified, clickWindow can have minimum value of 1 and maximum value of 240.
string Required Required
viewWindow Specfiies the time after the impression that conversion is tracked. integer Required Required
viewWindowUnit

Specifies the unit type of the view window.

  • DAY: If specified, viewWindow can have minimum value of 1 and maximum value of 45.
  • HOUR: If specified, viewWindow can have minimum value of 1 and maximum value of 48.
  • MINUTE: If specified, viewWindow can have minimum value of 1 and maximum value of 240.
string Required Required
viewBeaconValueDiscount Specifies the discount value percentage. If no value is specified, defaults to 0. number Required Required
beaconValuePc Specifies the value of each conversion. number Required Optional

Read Lines by ID

Returns line data for the specified line.

GET /traffic/lines/{id}

Parameters

Table 116 Read Lines by ID Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the line ID. integer Y

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/lines/1

Example Response

{
  "response": {
    "status": "PAUSED",
    "pacingModeType": "EVEN",
    "mediaType": "DISPLAY",
    "goalType": "CPC",
    "billingMethodType": "MARGIN",
    "budgetType": "CURRENCY",
    "dailyBudgetType": "SPECIFIED_AMOUNT",
    "marginType": "TOTAL_BUDGET",
    "budgetSchedule": {
      "startDateStr": "2018-03-10T05:00:00Z",
      "endDateStr": "2018-03-12T04:59:59Z",
      "id": 350105,
      "budget": 1600
    },
    "conversions": [
      {
        "clickWindowUnitType": "DAY",
        "viewWindowUnitType": "HOUR",
        "id": 15642,
        "name": "testNewPixel",
        "lineId": 355769,
        "beaconId": 762,
        "clickWindow": 4,
        "viewWindow": 2,
        "viewBeaconValueDiscount": 0,
        "beaconValuePc": 1.2,
        "acceptViewThrough": true
      }
    ],
    "id": 355769,
    "name": "traffic_api_margin_line",
    "orderId": 134,
    "bidPrice": 1,
    "goalAmount": 1,
    "maxGoal": 1,
    "dailyBudget": 11,
    "marginGoal": 25,
    "billingPrice": 2,
    "isNativeEnabled": false,
    "completionThreshold": 0,
    "avocThreshold": 0
  },
  "errors": null,
  "timeStamp": "2017-06-12T21:41:30Z"
}

Read Lines by Query

Retrieves a list of lines matching the specified query.

GET /traffic/lines?orderId={orderId}&page={page}&limit={limit}&sort={sort}&dir={dir}&query={query}

Parameters

All parameters are specified in the path of the URL endpoint or as a query appended to that URL.

Table 117 Read Lines by Query Parameters
Parameter Parameter Type Description Data Type Required
orderId query Specifies the campaign ID. integer Y
page query Specifies the number of pages. integer N
limit query Specifies the total number of items to return. The maximum value allowed is 100. integer N
sort query Specifies the column to sort by. string N
dir query Specifies the sort direction. Options include: asc, desc. string N
query query Search term. Use URL encoding conventions (i.e. a space should be replaced with a + or %20). string N

The response returns lines matching the specified query criteria.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/lines?orderId=1&page=1&limit=2

Example Response

{
  "response": [
    {
      "status": "PAUSED",
      "pacingModeType": "EVEN",
      "mediaType": "DISPLAY",
      "goalType": "CPC",
      "billingMethodType": "MARGIN",
      "budgetType": "CURRENCY",
      "dailyBudgetType": "SPECIFIED_AMOUNT",
      "marginType": "TOTAL_BUDGET",
      "budgetSchedule": {
        "startDateStr": "2018-03-10T05:00:00Z",
        "endDateStr": "2018-03-12T04:59:59Z",
        "id": 350106,
        "budget": 1600
      },
      "conversions": [
        {
          "clickWindowUnitType": "DAY",
          "viewWindowUnitType": "HOUR",
          "id": 15643,
          "name": "testNewPixel",
          "lineId": 355770,
          "beaconId": 762,
          "clickWindow": 4,
          "viewWindow": 2,
          "viewBeaconValueDiscount": 0,
          "beaconValuePc": 1.2,
          "acceptViewThrough": true
        }
      ],
      "id": 355770,
      "name": "traffic_api_margin_line2",
      "orderId": 134,
      "bidPrice": 1,
      "goalAmount": 1,
      "maxGoal": 1,
      "dailyBudget": 11,
      "marginGoal": 25,
      "billingPrice": 2,
      "isNativeEnabled": false,
      "completionThreshold": 0
    },
    {
      "status": "PAUSED",
      "pacingModeType": "EVEN",
      "mediaType": "DISPLAY",
      "goalType": "CPC",
      "billingMethodType": "MARGIN",
      "budgetType": "CURRENCY",
      "dailyBudgetType": "SPECIFIED_AMOUNT",
      "marginType": "TOTAL_BUDGET",
      "budgetSchedule": {
        "startDateStr": "2018-03-10T05:00:00Z",
        "endDateStr": "2018-03-12T04:59:59Z",
        "id": 350105,
        "budget": 1600
      },
      "id": 355769,
      "name": "traffic_api_margin_line",
      "orderId": 134,
      "bidPrice": 1,
      "goalAmount": 1,
      "maxGoal": 1,
      "dailyBudget": 11,
      "marginGoal": 25,
      "billingPrice": 2,
      "isNativeEnabled": false,
      "completionThreshold": 0
    }
  ],
  "errors": null,
  "timeStamp": "2017-06-13T00:22:21Z"
}

Create Lines

Adds a new display or video line.

  • To create a display line, specify DISPLAY as the line’s mediaType value.
  • To create a video line, specify VIDEO as the line’s mediaType value.
  • To create an audio line, specify AUDIO as the line’s mediaType value.

The response returns newly created line.

Parameters

All parameters are specified in the body of application/json payload.

Table 118 Create Lines Parameters
Parameter Parameter Type Description Data Type Required
name body Specifies the unique name of the line. string Y
orderId body

Specifies the campaign ID.

To learn more, see Campaigns.

integer Y
mediaType body

Specifies the the media type served by the line.

  • DISPLAY: To run an image ad, create a display line item within a campaign.
  • VIDEO: To run a video ad, create a video line item within a campaign.
  • AUDIO: To run an audio ad, create an audio line item within a campaign.
string Y
status body

Specifies the current status of the line.

  • ACTIVE: Active/running
  • PAUSED: Just ended
  • INACTIVE: Inactive/ended
string Y
goalType body

Specifies the goal type the platform will use to optimize line performance.

Different goal types are available depending on the mediaType value specified.

Display Line

  • NONE: This is the default option. With this goal type, Oath Ad Platforms DSP does not factor in a goal when it bids on impressions.
  • CPC: Establish a cost per click goal by specifying the target CPC (goalAmount) and Max CPM (bidPrice) amounts.
  • CPA: Establish a cost per action goal by specifying the Target CPA (goalAmount) and Max CPM (bidPrice) amounts.
  • VCPM: Establish a viewable CPM goal by specifying the target VCPM (goalAmount) and Max CPM (bidPrice) amounts.
  • ROAS: Establish a return on ad spend goal by specifying the Max ROAS (maxGoal) and Max CPM (bidPrice) amounts.
  • MAXINVIEWRATE: Maximize Viewability: Establish a soft goal to maximize viewability by specifying the Max CPM (bidPrice) amount.
  • OCPC: (Fixed CPM billing only, i.e. when billingMethodType is CPM_PRICE) Establish an optimized CPC goal by specifying the target CPC (goalAmount) and profit margin percentage (marginGoal).

Video Line

  • NONE: This is the default option. With this goal type, Oath Ad Platforms DSP does not factor in a goal when it bids on impressions.

  • CPC: Establish a cost per click goal by specifying the target CPC (goalAmount) and Max CPM (bidPrice) amounts.

  • CPCV: Establish a cost per single completed view goal by specifying the Target CPCV (goalAmount), Max CPM (bidPrice) amounts. When billingMethodType is CPM_PRICE, additionally specify Max CPCV (maxGoal) amount.

  • VCPM: Establish a viewable CPM goal for oCPM and Fixed CPM-billed lines by specifying the target VCPM (goalAmount) and Max CPM (bidPrice) amounts.

  • MAXCOMPLETIONRATE: Maximize Completion Rate: This is a soft optimization feature that helps improve the video completion rate over time without sacrificing impression delivery. For this goal type, specify the CPM (bidPrice) amount.

  • MAXCTR: Maximize CTR: This is a soft optimization feature that helps improve the click-through rate (CTR) over time without sacrificing impression delivery. For this goal type, specify the CPM (bidPrice) amount.

  • MAXINVIEWRATE: Maximize Viewability: This is a soft optimization feature that helps improve the video viewability as defined by third-party measurement provider Moat.

    A viewable video impression requires that 50% of video ad pixels are active and in the viewable portion of the viewer’s browser for two consecutive seconds. For this goal type, specify the CPM (bidPrice) amount.

  • COMPLETION_HARD_THRESHOLD: Specify Max CPM (bidPrice) amount and the completionThreshold percentage. (This goal type requires special role).

Audio Line

  • NONE: This is the default option. With this goal type, BrightRoll DSP does not factor in a goal when it bids on impressions.
  • ECPM: Establish a CPM goal by specifying the target ECPM (goalAmount) and Max ECPM (bidPrice) amounts.
string Y
goalAmount body Specifies the target amount for certain goal types. number Y
bidPrice body Specifies the maximum bid price (Maximum CPM Price) allowed for certain goal types. number Y
maxGoal body Specifies the maximum goal price. Required if the goalType is ROAS or CPCV. number Y
marginGoal body

Specifies the margin percentage.

[7]Required when goalType is OCPC.
number Y [7]
isNativeEnabled body

Specifies if the line can serve native ads. Native ads are not supported for video or audio lines.

  • If true, enables native ad support.
  • If false, disables native ad support; the default setting.

Important: Once the line is created, this attribute cannot be changed.

boolean N
pacingModeType body

Specifies the pacing mode.

  • EVEN: Spread the line budget evenly. If your daily budget is Auto Allocated, Oath Ad Platforms DSP spreads the total budget evenly over the line’s flight dates. If your daily budget is a Specified Amount, Oath Ad Platforms DSP spreads the specified daily budget evenly throughout the day.
  • ASAP: Bid on every impression opportunity that meets the line’s targeting criteria. If your daily budget is Auto Allocated, Oath Ad Platforms DSP delivers ASAP until all remaining budget is consumed. If your daily budget is a Specified Amount, Oath Ad Platforms DSP delivers ASAP until the specified amount is consumed.
  • AHEAD: Provides greater control over how line budgets are allocated during a flight by enabling you to over-pace daily budgets. If the daily budget is user-specified, the line will over-pace the daily budget every day until the total budget is consumed. The amount over-spent is determined by the pacingAcceleration specified. If the line’s daily budget is auto-allocated, the line’s spend rate is dynamically determined based on the line’s remaining total budget, the remaining days in the flight, and the line’s pacingAcceleration.
string Y
pacingAcceleration body

Specifies the percentage over the daily budget that the line may spend per day.

Ahead pacing is the product of the even pacing value multiplied by the pacing acceleration value: (remaining budget/remaining days) * pacing acceleration value.

[8]Required if the value of pacingModeType is AHEAD.
number Y [8]
budgetType body

Specifies whether the line uses impression-based budgeting or budgeting based on US dollars for the line.

  • CURRENCY: Budget based on US Dollars.
  • IMPRESSION: Budget based on impressions. Impression-based budgeting enables you to control the number of impressions a line delivers, and respects the line’s Max CPM price, daily pacing, optimization goals, and targeting options.
string Y
dailyBudgetType body

Specifies the daily budget type is used to indicate how the line’s budget is allocated.

  • SPECIFIED_AMOUNT: Specify a daily spend cap for the line in the dailyBudget field.
  • AUTO_ALLOCATED: Allocation based on the overall budget and the number of days left in the line’s flight.
string N
dailyBudget body

Specifies the daily budget amount.

[9]Required if the budgetType is CURRENCY and dailyBudgetType is SPECIFIED_AMOUNT.
number Y [9]
impBudget body

Specifies the total number of impressions bought.

[10]Required when budgetType is IMPRESSION.
impression Y [10]
impDailyBudget body

Specifies the total number of impressions bought per day.

[11]Required when budgetType is IMPRESSION.
integer Y [11]
billingMethodType body

Specifies the billing method.

  • CPM_PRICE: With Fixed CPM billing, you pay a fixed price per 1000 impressions.
  • CPC: With Fixed CPC billing, you pay a fixed price per click.
  • MARGIN: (oCPM) With oCPM billing, Oath Ad Platforms DSP predicts the probability that events (such as clicks, conversions, video completions, or impressions) will occur.
  • CPCV: (Video Line only) Cost Per Completed View for video. With CPCV billing, you only pay for completed video views. Note: If you choose CPCV, you must set pacingMode to EVEN and you can only set goalType to either CPCV or NONE.
string Y
billingPrice body

Specifies the amount paid based on the specified billingMethodType.

  • When billingMethodType is MARGIN (oCPM), specifies the profit margin percentage.
  • When billingMethodType is CPCV, this field represents the amount you want to pay for each completed video view.
  • When billingMethodType is CPM_PRICE, this field represents the amount you want to pay for each 1000 impressions.
  • When billingMethodType is CPC, this field represents the amount you want to pay for each click.
number N
marginType body

Specifies how the margin is calculated.

  • TOTAL_BUDGET: Margin is calculated as a percentage of advertiser spend, which includes all costs (inventory, Yahoo fees, and variable costs).
  • BUYER_COST: Margin is calculated as a percentage of the buyer cost where buyer cost = inventory cost + Oath fees. This option excludes all variable costs.

Note: This is available to self-serve accounts only.

string N
completionThreshold body

Specifies the completion threshold percentage.

[12]Required when goalType is COMPLETION_HARD_THRESHOLD.
integer Y [12]
budgetSchedule body

Specifies the line’s budget schedule.

To learn more, see Budget Schedule.

object Y
lineFees body

Track external costs such as ad serving, measurement, and brand safety costs. To help you better manage your margins, you can add up to six variable CPM costs to each line for tracking purposes.

To learn more, see Line Fees.

Note: This is available to self-serve accounts only.

object N
conversions body Oath Ad Platforms DSP can optimize a line with multiple conversion rules when you establish conversion values. Refer to conversions object. To obtain the available conversions, see Read Advertiser Beacon Lookups. object N

Example Request

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines

Example: Create (Margin) oCPM Display Line

To create a DISPLAY line with MARGIN (oCPM) billing type, refer to the table and payload below.

Field Value Type
mediaType DISPLAY string
billingMethodType MARGIN string
billingPrice Desired % profit margin number

Example Payload

{
  "name": "traffic_api_margin_line_3",
  "orderId": 134,
  "status": "PAUSED",
  "mediaType": "DISPLAY",
  "pacingModeType": "EVEN",
  "budgetType": "CURRENCY",
  "goalType": "CPC",
  "billingMethodType": "MARGIN",
  "dailyBudgetType": "SPECIFIED_AMOUNT",
  "dailyBudget": 11,
  "billingPrice": 2,
  "marginType": "TOTAL_BUDGET",
  "bidPrice": 1,
  "maxGoal": 1,
  "marginGoal": 25,
  "isAutoBudgetEnabled": false,
  "goalAmount": 1,
  "impDailyBudget": null,
  "isNativeEnabled": false,
  "completionThreshold": 0,
  "conversions": [
    {
      "name": "testNewPixel",
      "lineId": 0,
      "beaconId": 762,
      "acceptViewThrough": true,
      "viewWindow": 2,
      "clickWindow": 4,
      "clickWindowUnitType": "DAY",
      "viewWindowUnitType": "HOUR",
      "beaconValuePc": 1.2,
      "viewBeaconValueDiscount": null
    }
  ],
  "budgetSchedule": {
    "startDateStr": "2018-03-10",
    "endDateStr": "2018-03-11",
    "budget": 1600
  },
  "lineFees": []
}

Example: Create Impression Budget Display Line

Field Value Type
mediaType DISPLAY string
billingMethodType CPM_PRICE string
billingPrice Amount you want to pay for each 1000 impressions number
budgetType IMPRESSION string
impBudget Total number of impressions you plan to buy integer

Example Payload

{
  "name": "imp_line2",
  "orderId": 7633,
  "status": "PAUSED",
  "mediaType": "DISPLAY",
  "pacingModeType": "EVEN",
  "budgetType": "IMPRESSION",
  "goalType": "VCPM",
  "billingMethodType": "CPM_PRICE",
  "dailyBudgetType": "SPECIFIED_AMOUNT",
  "dailyBudget": 11,
  "impBudget": 1006,
  "billingPrice": 1,
  "marginType": "TOTAL_BUDGET",
  "bidPrice": 1,
  "maxGoal": 1.1,
  "marginGoal": 25,
  "isAutoBudgetEnabled": false,
  "goalAmount": 1,
  "impDailyBudget": 2,
  "isNativeEnabled": false,
  "completionThreshold": 0,
  "conversions": [],
  "budgetSchedule": {
    "startDateStr": "2018-03-10",
    "endDateStr": null,
    "budget": 1
  },
  "lineFees": []
}

Example: Create oCPC Display Line

To create a DISPLAY line with oCPC goal type, refer to the table and payload below.

Field Value Type
mediaType DISPLAY string
billingMethodType CPM_PRICE string
goalType OCPC string
goalAmount Target CPC number
marginGoal Profit Margin Goal % number

Example Payload

{
  "name": "test-ocpc",
  "orderId": 200793,
  "mediaType": "DISPLAY",
  "billingMethodType": "CPM_PRICE",
  "billingPrice": 1,
  "marginType": "TOTAL_BUDGET",
  "dailyBudgetType": "AUTO_ALLOCATED",
  "bidPrice": 1,
  "goalType": "OCPC",
  "maxGoal": 1.1,
  "marginGoal": 25,
  "status": "ACTIVE",
  "goalAmount": 1.1,
  "impDailyBudget": null,
  "impBudget": 1255000,
  "pacingModeType": "EVEN",
  "isNativeEnabled": false,
  "completionThreshold": 0,
  "conversions": [],
  "budgetSchedule": {
    "startDateStr": "2017-06-17",
    "endDateStr": "2017-11-01",
    "budget": 1255
  },
  "lineFees": []
}

Example: Create CPCV Video Line

To create a VIDEO line with CPCV billing and goal, refer to the table and payload below.

Field Value Type
mediaType VIDEO string
billingMethodType CPCV string
goalType CPCV string
billingPrice Amount you want to pay for each completed video view number
bidPrice Max CPM price string
goalAmount Target CPCV number
pacingMode EVEN string
maxGoal Maximum goal price number

Example Payload

{
  "name": "test-video5599",
  "orderId": 312515,
  "status": "ACTIVE",
  "mediaType": "VIDEO",
  "pacingModeType": "EVEN",
  "budgetType": "CURRENCY",
  "goalType": "CPCV",
  "billingMethodType": "CPCV",
  "dailyBudgetType": "SPECIFIED_AMOUNT",
  "dailyBudget": 1.25,
  "billingPrice": 1,
  "marginType": "TOTAL_BUDGET",
  "bidPrice": 1,
  "maxGoal": 1,
  "marginGoal": 25,
  "isAutoBudgetEnabled": false,
  "goalAmount": 1,
  "isNativeEnabled": false,
  "completionThreshold": 0,
  "budgetSchedule": {
    "startDateStr": "2018-03-10",
    "endDateStr": "2018-03-10",
    "budget": 1000
  }
}

Example: Create Line w/ Variable Costs

To create a line with variable cost tracking, refer to the table and payload below.

Field Type
lineFees object

Example Payload

{
  "name": "test194",
  "orderId": 308869,
  "status": "PAUSED",
  "mediaType": "DISPLAY",
  "pacingModeType": "EVEN",
  "budgetType": "IMPRESSION",
  "goalType": "CPC",
  "billingMethodType": "CPM_PRICE",
  "dailyBudgetType": "SPECIFIED_AMOUNT",
  "impBudget": 1006,
  "impDailyBudget": 33,
  "dailyBudget": null,
  "billingPrice": 1,
  "marginType": "TOTAL_BUDGET",
  "bidPrice": 1,
  "maxGoal": 1,
  "marginGoal": 25,
  "isAutoBudgetEnabled": false,
  "goalAmount": 1,
  "isNativeEnabled": false,
  "completionThreshold": 0,
  "conversions": [],
  "budgetSchedule": {
    "startDateStr": "2018-03-10",
    "endDateStr": "2018-03-10",
    "budget": 1000
  },
  "lineFees": [
    {
      "typeName": "AD_SERVING",
      "name": "amc",
      "fee": 0.86
    }
  ]
}

Update Lines

Updates an existing line.

The response returns the updated line.

Parameters

All parameters are specified in the body of the application/json payload.

Table 119 Update Lines
Parameter Parameter Type Description Data Type Required
id body Specifies the line ID. integer Y
name body Specifies the unique name of the line. string N
orderId body

Specifies the campaign ID.

To learn more, see Campaigns.

integer N
mediaType body

Specifies the the media type served by the line.

  • DISPLAY: To run an image ad, create a display line item within a campaign.
  • VIDEO: To run a video ad, create a video line item within a campaign.
  • AUDIO: To run an audio ad, create an audio line item within a campaign.
string Y
status body

Specifies the current status of the line.

  • ACTIVE: Active/running
  • PAUSED: Just ended
  • INACTIVE: Inactive/ended
string N
goalType body

Specifies the goal type the platform will use to optimize line performance.

Different goal types are available depending on the mediaType value specified.

Display Line

  • NONE: This is the default option. With this goal type, Oath Ad Platforms DSP does not factor in a goal when it bids on impressions.
  • CPC: Establish a cost per click goal by specifying the target CPC (goalAmount) and Max CPM (bidPrice) amounts.
  • CPA: Establish a cost per action goal by specifying the Target CPA (goalAmount) and Max CPM (bidPrice) amounts.
  • VCPM: Establish a viewable CPM goal by specifying the target VCPM (goalAmount) and Max CPM (bidPrice) amounts.
  • ROAS: Establish a return on ad spend goal by specifying the Max ROAS (maxGoal) and Max CPM (bidPrice) amounts.
  • MAXINVIEWRATE: Maximize Viewability: Establish a soft goal to maximize viewability by specifying the Max CPM (bidPrice) amount.
  • OCPC: (Fixed CPM billing only, i.e. when billingMethodType is CPM_PRICE) Establish an optimized CPC goal by specifying the target CPC (goalAmount) and profit margin percentage (marginGoal).

Video Line

  • NONE: This is the default option. With this goal type, Oath Ad Platforms DSP does not factor in a goal when it bids on impressions.

  • CPC: Establish a cost per click goal by specifying the target CPC (goalAmount) and Max CPM (bidPrice) amounts.

  • CPCV: Establish a cost per single completed view goal by specifying the Target CPCV (goalAmount), Max CPM (bidPrice) amounts. When billingMethodType is CPM_PRICE, additionally specify Max CPCV (maxGoal) amount.

  • VCPM: Establish a viewable CPM goal for oCPM and Fixed CPM-billed lines by specifying the target VCPM (goalAmount) and Max CPM (bidPrice) amounts.

  • MAXCOMPLETIONRATE: Maximize Completion Rate: This is a soft optimization feature that helps improve the video completion rate over time without sacrificing impression delivery. For this goal type, specify the CPM (bidPrice) amount.

  • MAXCTR: Maximize CTR: This is a soft optimization feature that helps improve the click-through rate (CTR) over time without sacrificing impression delivery. For this goal type, specify the CPM (bidPrice) amount.

  • MAXINVIEWRATE: Maximize Viewability: This is a soft optimization feature that helps improve the video viewability as defined by third-party measurement provider Moat.

    A viewable video impression requires that 50% of video ad pixels are active and in the viewable portion of the viewer’s browser for two consecutive seconds. For this goal type, specify the CPM (bidPrice) amount.

  • COMPLETION_HARD_THRESHOLD: Specify Max CPM (bidPrice) amount and the completionThreshold percentage. (This goal type requires special role).

Audio Line

  • NONE: This is the default option. With this goal type, BrightRoll DSP does not factor in a goal when it bids on impressions.
  • ECPM: Establish a CPM goal by specifying the target ECPM (goalAmount) and Max ECPM (bidPrice) amounts.
string N
goalAmount body Specifies the target amount for certain goal types. number N
bidPrice body Specifies the maximum bid price (Maximum CPM Price) allowed for certain goal types. number Y
maxGoal body Specifies the maximum goal price. Required if the goalType is ROAS or CPCV. number N
marginGoal body

Specifies the margin percentage.

[13]Required when goalType is OCPC.
number N [13]
isNativeEnabled body

Specifies if the line can serve native ads. Native ads are not supported for video or audio lines.

  • If true, enables native ad support.
  • If false, disables native ad support; the default setting.

Important: Once the line is created, this attribute cannot be changed.

boolean N
pacingModeType body

Specifies the pacing mode.

  • EVEN: Spread the line budget evenly. If your daily budget is Auto Allocated, Oath Ad Platforms DSP spreads the total budget evenly over the line’s flight dates. If your daily budget is a Specified Amount, Oath Ad Platforms DSP spreads the specified daily budget evenly throughout the day.
  • ASAP: Bid on every impression opportunity that meets the line’s targeting criteria. If your daily budget is Auto Allocated, Oath Ad Platforms DSP delivers ASAP until all remaining budget is consumed. If your daily budget is a Specified Amount, Oath Ad Platforms DSP delivers ASAP until the specified amount is consumed.
  • AHEAD: Provides greater control over how line budgets are allocated during a flight by enabling you to over-pace daily budgets. If the daily budget is user-specified, the line will over-pace the daily budget every day until the total budget is consumed. The amount over-spent is determined by the pacingAcceleration specified. If the line’s daily budget is auto-allocated, the line’s spend rate is dynamically determined based on the line’s remaining total budget, the remaining days in the flight, and the line’s pacingAcceleration.
string Y
pacingAcceleration body

Specifies the percentage over the daily budget that the line may spend per day.

Ahead pacing is the product of the even pacing value multiplied by the pacing acceleration value: (remaining budget/remaining days) * pacing acceleration value.

[14]Required if the value of pacingModeType is AHEAD.
number N [14]
budgetType body

Specifies whether the line uses impression-based budgeting or budgeting based on US dollars for the line.

  • CURRENCY: Budget based on US Dollars.
  • IMPRESSION: Budget based on impressions. Impression-based budgeting enables you to control the number of impressions a line delivers, and respects the line’s Max CPM price, daily pacing, optimization goals, and targeting options.
string Y
dailyBudgetType body

Specifies the daily budget type is used to indicate how the line’s budget is allocated.

  • SPECIFIED_AMOUNT: Specify a daily spend cap for the line in the dailyBudget field.
  • AUTO_ALLOCATED: Allocation based on the overall budget and the number of days left in the line’s flight.
string N
dailyBudget body

Specifies the daily budget amount.

[15]Required if the budgetType is CURRENCY and dailyBudgetType is SPECIFIED_AMOUNT.
number N [15]
impBudget body

Specifies the total number of impressions bought.

[16]Required when budgetType is IMPRESSION.
impression N [16]
impDailyBudget body

Specifies the total number of impressions bought per day.

[17]Required when budgetType is IMPRESSION.
integer N [17]
billingMethodType body

Specifies the billing method.

  • CPM_PRICE: With Fixed CPM billing, you pay a fixed price per 1000 impressions.
  • CPC: With Fixed CPC billing, you pay a fixed price per click.
  • MARGIN: (oCPM) With oCPM billing, Oath Ad Platforms DSP predicts the probability that events (such as clicks, conversions, video completions, or impressions) will occur.
  • CPCV: (Video Line only) Cost Per Completed View for video. With CPCV billing, you only pay for completed video views. Note: If you choose CPCV, you must set pacingMode to EVEN and you can only set goalType to either CPCV or NONE.
string N
billingPrice body

Specifies the amount paid based on the specified billingMethodType.

  • When billingMethodType is MARGIN (oCPM), specifies the profit margin percentage.
  • When billingMethodType is CPCV, this field represents the amount you want to pay for each completed video view.
  • When billingMethodType is CPM_PRICE, this field represents the amount you want to pay for each 1000 impressions.
  • When billingMethodType is CPC, this field represents the amount you want to pay for each click.
number N
marginType body

Specifies how the margin is calculated.

  • TOTAL_BUDGET: Margin is calculated as a percentage of advertiser spend, which includes all costs (inventory, Yahoo fees, and variable costs).
  • BUYER_COST: Margin is calculated as a percentage of the buyer cost where buyer cost = inventory cost + Oath fees. This option excludes all variable costs.

Note: This is available to self-serve accounts only.

string N
completionThreshold body

Specifies the completion threshold percentage.

[18]Required when goalType is COMPLETION_HARD_THRESHOLD.
integer N [18]
budgetSchedule body

Specifies the line’s budget schedule.

To learn more, see Budget Schedule.

object N
lineFees body

Track external costs such as ad serving, measurement, and brand safety costs. To help you better manage your margins, you can add up to six variable CPM costs to each line for tracking purposes.

To learn more, see Line Fees.

Note: This is available to self-serve accounts only.

object N
conversions body Oath Ad Platforms DSP can optimize a line with multiple conversion rules when you establish conversion values. Refer to conversions object. To obtain the available conversions, see Read Advertiser Beacon Lookups. object N

Example: Activate Paused Line

The following payload shows how to change the line status from PAUSED to ACTIVE.

Example Request

PUT https://dspapi.admanagerplus.yahoo.com/traffic/lines/352534

Example Payload

{
  "status": "ACTIVE"
}

Example: Update Line Budget & Start/End Dates

The following payload shows how to update the total budget and start/end dates of a line.

Example Request

PUT https://dspapi.admanagerplus.yahoo.com/traffic/lines/352534

Example Payload

{
  "budgetSchedule": {
    "startDateStr": "2017-09-22",
    "endDateStr": "2017-11-22",
    "budget": 250
  }
}

Example: Update Line with Conversion Pixel

The following payload shows how to add a conversion pixel to an existing line.

Example Request

PUT https://dspapi.admanagerplus.yahoo.com/traffic/lines/355775

Example Payload

{
  "conversions": [
    {
      "name": "testNewPixel55",
      "lineId": 355775,
      "beaconId": 762,
      "acceptViewThrough": true,
      "viewWindow": 2,
      "clickWindow": 4,
      "clickWindowUnitType": "DAY",
      "viewWindowUnitType": "HOUR",
      "beaconValuePc": 1.2,
      "viewBeaconValueDiscount": null
    }
  ]
}

Delete Lines

Line deletion is not supported by the API.