Lines

Overview

In BrightRoll DSP, a line (or line-item) is subcomponent of a campaign that specifies an advertising strategy. Every line is defined by one or more ads 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

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

Fields

The Line object contains the following fields:

Name Description Type Add Update
id ID of the line. integer N/A Required
name Name of the line. Must be unique. text Required Optional
orderId Order (campaign) ID. Refer to Campaigns. integer Required Optional
mediaType

Line type.

  • 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.
text Required Optional
status

Current status of the line.

  • ACTIVE - Active/Running
  • PAUSED - Just ended
  • INACTIVE - Not active/Ended

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
text Required Optional
goalType

Goal type of the line.

Display Line

  • NONE - This is the default option. With this goal type, BrightRoll 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, BrightRoll 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 - (This goal type requires special role). Specify Max CPM (bidPrice) amount and the completionThreshold percentage.
text Required Optional
goalAmount Target amount for certain goal types. See goalType for more information. float Required Optional
bidPrice Maximum bid price for certain goal types. See goalType for more information. float Required Required
maxGoal Maximum goal price for (ROAS and CPCV) goal types. float Required Optional
marginGoal Profit margin percentage. (1): Required when goalType is OCPC. float Required (1) Optional
isNativeEnabled

Indicates if the line can include native ads. Native ads are not supported at this time for video lines. Important: Once the line is created, this value can not be changed.

  • true - Enable native traffic.
  • false - (Default) Disable native traffic.
boolean Optional Optional
pacingModeType
  • EVEN - Spread the line budget evenly. If your daily budget is Auto Allocated, BrightRoll DSP spreads the total budget evenly over the line’s flight dates. If your daily budget is a Specified Amount, BrightRoll 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, BrightRoll DSP delivers ASAP until all remaining budget is consumed. If your daily budget is a Specified Amount, BrightRoll DSP delivers ASAP until the specified amount is consumed.
text Required Optional
budgetType

Set up impression-based budgeting or budgeting based on US dollars for the line. Impression-based budgeting allows 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.

  • CURRENCY - Budget based on US Dollars.
  • IMPRESSION - Budget based on impressions.
text Required Optional
dailyBudgetType

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.
text Optional Optional
dailyBudget Daily budget amount. (1): Required when budgetType is CURRENCY and dailyBudgetType is SPECIFIED_AMOUNT. float Required (1) Optional
impBudget Total number of impressions you plan to buy. (1) Required when budgetType is IMPRESSION. integer Required (1) Optional
impDailyBudget Total number of number of impressions you want to purchase each day. (1) Required when budgetType is IMPRESSION and dailyBudgetType is SPECIFIED_AMOUNT. integer Required (1) Optional
billingMethodType
  • 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, BrightRoll 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.
text Required Optional
billingPrice

When billingMethodType is MARGIN (oCPM), this field represents the desired profit margin in %.

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.

float Optional Optional
marginType

Specify how margin is calculated. NOTE This is available to self-serve accounts only.

  • 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 + Yahoo fees. This option excludes all variable costs.
text Optional Optional
completionThreshold Completion threshold percentage. (1). Required when goalType is COMPLETION_HARD_THRESHOLD. integer Required (1) Optional
budgetSchedule Line’s budget schedule. Refer to budgetSchedule object. 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. Refer to lineFees object. NOTE This is available to self-serve accounts only. object Optional Optional
conversions BrightRoll DSP can optimize a line with multiple conversion rules when you establish conversion values. Refer to conversions object. To obtain the available conversions, see Beacon Lookups. object Optional Optional

budgetSchedule object

The budgetSchedule object contains the following fields:

Name Description Type Add Update
id ID of the budget schedule. integer N/A N/A
startDate Line start date in yyyy-MM-dd format. text Required Required
endDate Line end date in yyyy-MM-dd format. text Required Required
budget Total budget for the line. float Required Optional

lineFees object

Note

This feature is only available for self-serve accounts.

The lineFees object contains the following fields:

Name Description Type Add Update
id ID of the record. integer N/A N/A
name User-specified name. text Required Required
fee CPM amount. This is the amount you need to pay per 1000 impressions. float Required Optional
variableCostType

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.
text Required Required

conversions object

The conversions object contains the following fields:

Name Description Type Add Update
id ID of the conversion pixel. integer N/A N/A
name Name of the conversion pixel. string Required Required
beaconId ID of the conversion pixel. integer Required Required
acceptViewThrough

Indicate whether to accept view through.

  • true - Must supply values for viewWindow and viewWindowUnit.
  • false
boolean Required Optional
clickWindow Amount of time after a click that the conversion is tracked. integer Required Required
clickWindowUnit

Unit type for click window.

  • DAY - When selected, clickWindow can have minimum value of 1 and maximum value of 45.
  • HOUR - When selected, clickWindow can have minimum value of 1 and maximum value of 48.
  • MINUTE - When selected, clickWindow can have minimum value of 1 and maximum value of 240.
string Required Required
viewWindow Amount of time after a impression that the conversion is tracked. integer Required Required
viewWindowUnit

Unit type for view window.

  • DAY - When selected, viewWindow can have minimum value of 1 and maximum value of 45.
  • HOUR - When selected, viewWindow can have minimum value of 1 and maximum value of 48.
  • MINUTE - When selected, viewWindow can have minimum value of 1 and maximum value of 240.
string Required Required
viewBeaconValueDiscount Discount in %. If no value is supplied, it defaults to 0. float Optional Optional
beaconValuePc Amount that each conversion is worth. float Required Optional

Read Line (Single)

To retrieve data for a specific Line, make a GET call with the id parameter.

GET https://dspapi.admanagerplus.yahoo.com/traffic/lines/{id}
Name Description Type
id Line ID (Required) integer

The response will be the Line associated with the given ID.

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 (Filtered)

To retrieve a filtered list of Lines, make a GET call with the supported query parameters.

GET https://dspapi.admanagerplus.yahoo.com/lines?orderId={orderId}&page={page}&limit={limit}&sort={sort}&dir={dir}&query={search query}
Name Description Type
orderId Campaign ID (Required) integer
page Page number integer
limit Total number of items to return. Maximum allowed value is 100. integer
sort Column to sort by text
dir Sort direction. Valid values: asc, desc text
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text

The response will be the list of Lines matching the given filter(s).

Example Request

GET https://dspapi.admanagerplus.yahoo.com/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 Line

To create a new display Line, make a POST call with mediaType set to DISPLAY in the Line object payload.

To create a new video Line, make a POST call with mediaType set to VIDEO in the Line object payload.

The response will be the newly created Line.

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 text
billingMethodType MARGIN text
billingPrice Desired % profit margin float

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 text
billingMethodType CPM_PRICE text
billingPrice Amount you want to pay for each 1000 impressions float
budgetType IMPRESSION text
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 text
billingMethodType CPM_PRICE text
goalType OCPC text
goalAmount Target CPC float
marginGoal Profit Margin Goal % float

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 text
billingMethodType CPCV text
goalType CPCV text
billingPrice Amount you want to pay for each completed video view float
bidPrice Max CPM price text
goalAmount Target CPCV float
pacingMode EVEN text
maxGoal Maximum goal price float

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.

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
    }
  ]
}

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 Line

Line deletion is not supported by the API.