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 Verizon Media DSP, a line is subcomponent of a campaign that specifies an advertising strategy. Verizon Media DSP defines each line by one or more ads, a goal type, and a set of budgetary and targeting parameters.
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 you can specify budgets at both the campaign and line level; flight dates, frequency caps, and budgets specified at the campaign level override line-level configurations.
Endpoint¶
/traffic/lines
The action taken depends on the HTTP method and the parameters specified.
Use the
GET
method to read an existing line.Use the
POST
method to create a new line.Use the
PUT
method to update an existing line.
Resources¶
The platform provides the following resources for managing and tracking lines:
lines
schedules
feeList
conversionList
Line Object¶
The Line
object contains the following fields:
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
|
Specifies the line ID. |
|
N/A |
Required |
|
Specifies the unique name of the line. |
|
Required |
Optional |
|
Specifies the campaign ID. To learn more, see Campaigns. |
|
Required |
Optional |
|
Specifies the the media type served by the line. Allowed values:
|
|
Required |
N/A 1 |
|
Specifies the current status of the line. Allowed values:
The following status types are read-only:
|
|
Required |
Optional |
|
Specifies the goal type the platform will use to optimize line performance. Different goal types are available depending on the Display Line
Video Line
Audio Line
|
|
Required |
Optional |
|
Specifies the goal mode. The goal mode determines whether the optimizes for line delivery or line performance. Allowed values:
|
|
Optional 2 |
Optional |
|
Specifies the target amount for certain goal types.
|
|
Required 3 |
Optional |
|
Specifies the maximum bid price (Maximum CPM Price) allowed for certain goal types. |
|
Required |
Optional |
|
Specifies the maximum goal price.
|
|
Required 4 |
Optional |
|
Specifies the margin percentage.
|
|
Required 5 |
Optional |
|
Specifies if the line can serve native ads. Native ads are not supported at this time for video lines.
|
|
Optional 6 |
N/A 7 |
|
Specifies the pacing mode. Allowed values:
|
|
Optional |
Optional 8 |
|
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:
|
|
Required 9 |
Optional 10 |
|
Defines the objective of the app marketing line. It can be set for a line with CPI goal type. Allowed values:
|
|
Optional 11 |
Optional 12 |
|
The URL of the app that line is running for. It should be Google app URL if the line is targeting Android devices and Apple store app URL if the line is targeting IOS devices. Example values: https://play.google.com/store/apps/details?id=com.espn.score_center&hl=en_US, https://apps.apple.com/pe/app/instagram/id389801252
|
|
Optional 13 |
Optional 14 |
|
The region (country) of the Google play store or Apple app store where the app is uploaded. Allowed values:
|
|
Optional 15 |
Optional 16 |
|
The app ID is generated based on the appUrl and appLocale provided. Example values: com.espn.score_center, 389801252 |
|
N/A |
N/A |
|
Specifies whether the line uses impression-based budgeting or budgeting based on US dollars for the line. Allowed values:
|
|
Optional |
Optional |
|
Specifies the billing method. Allowed values:
|
|
Required |
Optional |
|
Specifies the amount paid based on the specified
|
|
Optional |
Optional |
|
Specifies how the margin is calculated. Allowed values:
Note: This is available to self-serve accounts only. |
|
Required |
Optional |
|
Specifies the completion threshold percentage.
|
|
Required 17 |
Optional |
|
Specifies either a single budget schedule or multiple budget schedules. To learn more, see Schedules Object. Note: Multiple schedules are supported only when budgetType is CURRENCY. |
|
Required |
Optional |
|
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 FeeList Object. Note: This is available to self-serve accounts only. |
|
Optional |
Optional |
|
Verizon Media DSP can optimize a line with multiple conversion rules when you establish conversion values. To learn more, see ConversionList Object. |
|
Optional |
Optional |
|
A bid multiplier is a targeting-specific configuration that specifies the relative weight that should be given to targeted ad placement opportunities. To learn more, see Bid Multiplier Cap Object. |
|
N/A |
N/A |
Schedules Object¶
The schedules
object contains the following fields:
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
|
Specifies ID of the budget schedule. |
|
N/A |
N/A |
|
Specifies the name of the schedule.
|
|
Required [#]_ |
Optional |
|
Specifies the start date of the line in the yyyy-MM-dd format. |
|
Required |
Required |
|
Specifies the end date of the line in the yyyy-MM-dd format. |
|
Required |
Required |
|
Specifies the total budget of the line.
|
|
Required [#]_ |
Optional |
|
Specifies the daily budget amount.
|
|
Required [#]_ |
Optional |
|
Specifies the total number of impressions bought.
|
|
Required [#]_ |
Optional [#]_ |
|
Specifies the total number of impressions bought per day.
|
|
Required [#]_ |
Optional [#]_ |
|
Specifies the daily budget type. Allowed values:
|
|
Required |
Optional |
FeeList Object¶
Note
This feature is only available for self-serve accounts.
The feeList
object contains the following fields:
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
|
Specifies the line fee ID. |
|
N/A |
Required |
|
Specifies a user-defined name. |
|
Required |
Optional |
|
Specifies the CPM amount: the amount you must pay per thousand impressions. |
|
Required |
Optional |
|
Specifies the variable cost type. Allowed values:
Note: Once a variable cost is created, it’s type cannot be changed. |
|
Required |
N/A |
ConversionList Object¶
Verizon Media DSP can optimize a line with multiple conversion rules when you establish conversion values.
To obtain the available conversions, see Read Advertiser Beacon Lookups.
Each entry in the conversionList
object contains the following fields:
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
|
Specifies the conversion pixel ID. |
|
N/A |
Required |
|
Name of the conversion pixel. The name can not be specified or changed. |
|
N/A |
N/A |
|
Specifies the conversion pixel ID. |
|
Required |
Required |
|
Specifies the line ID. Note: When updating an existing conversion, setting this field to |
|
Optional |
Required |
|
Specifies whether a view through is accepted. |
|
Required |
Optional |
|
Specifies the amount of time after a click that the conversion is tracked. |
|
Required |
Optional |
|
Specifies the click window unit type. Allowed values:
|
|
Required |
Optional |
|
Specfiies the time after the impression that conversion is tracked. |
|
Required |
Optional |
|
Specifies the unit type of the view window. Allowed values:
|
|
Required |
Optional |
|
Specifies the discount value percentage. If no value is specified, defaults to |
|
Optional |
Optional |
|
Specifies the value of each conversion. |
|
Required |
Optional |
Bid Multiplier Cap Object¶
The bidMultiplierCap
object contains the following fields:
Field |
Description |
Data Type |
Create |
Update |
---|---|---|---|---|
|
The current bid multiplier cap for the line. |
|
N/A |
N/A |
Read Line¶
Get data for a specific line.
GET /traffic/lines/{id}
Parameters¶
Parameters |
Parameter Type |
Description |
Data Type |
Required |
---|---|---|---|---|
|
path |
Specifies the line ID. |
|
Y |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/lines/630162
Example Response¶
{
"response": {
"id": 630162,
"name": "display-line-multi-budget-15",
"orderId": 462137,
"bidPrice": 1,
"goalAmount": 1.34,
"maxGoal": 1.34,
"marginGoal": 25,
"billingPrice": 1,
"completionThreshold": 0,
"isNativeEnabled": false,
"status": "PAUSED",
"pacingModeType": "EVEN",
"mediaType": "DISPLAY",
"goalModeType": "SOFT",
"goalType": "CPC",
"billingMethodType": "MARGIN",
"marginType": "TOTAL_BUDGET",
"budgetType": "CURRENCY",
"schedules": [
{
"id": 1307654,
"name": "s2",
"budget": 2000,
"startDateStr": "2020-09-29T05:00:00Z",
"endDateStr": "2020-12-29T05:59:59Z",
"dailyBudgetType": "AUTO_ALLOCATED"
},
{
"id": 1307653,
"name": "s1",
"budget": 1000,
"dailyBudget": 150,
"startDateStr": "2020-08-11T05:00:00Z",
"endDateStr": "2020-09-29T04:59:59Z",
"dailyBudgetType": "SPECIFIED_AMOUNT"
}
],
"feeList": [
{
"id": 12584,
"name": "amc",
"fee": 0.86,
"typeName": "AD_SERVING"
}
],
"conversionList": [
{
"id": 7386,
"lineId": 630162,
"beaconId": 15776560,
"acceptViewThrough": true,
"clickWindow": 4,
"viewWindow": 2,
"name": "test rule 1",
"viewBeaconValueDiscount": 0,
"beaconValuePc": 1.05,
"clickWindowUnitType": "DAY",
"viewWindowUnitType": "HOUR"
}
]
},
"errors": null,
"timeStamp": "2020-07-14T02:03:50.037Z"
}
Read Lines¶
Get a filtered list of lines.
GET /traffic/lines?orderId={orderId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}
All of the accepted parameters are query parameters.
Parameters¶
Parameter |
Description |
Data Type |
Required |
---|---|---|---|
|
Specifies the campaign ID. |
|
Y |
|
Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a |
|
N |
|
Specifies the page number. |
|
N |
|
Specifies the total number of items to return. Maximum allowed value is |
|
N |
|
Specifies the column to sort by. |
|
N |
|
Specifies the sort direction. Allowed values:
|
|
N |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/lines?orderId=462137&limit=2&sort=id&dir=desc&seatId=2
Example Response¶
{
"response": [
{
"id": 630162,
"name": "display-line-multi-budget-15",
"orderId": 462137,
"bidPrice": 1,
"goalAmount": 1.34,
"maxGoal": 1.34,
"marginGoal": 25,
"billingPrice": 1,
"completionThreshold": 0,
"isNativeEnabled": false,
"status": "PAUSED",
"pacingModeType": "EVEN",
"mediaType": "DISPLAY",
"goalModeType": "SOFT",
"goalType": "CPC",
"billingMethodType": "MARGIN",
"marginType": "TOTAL_BUDGET",
"budgetType": "CURRENCY",
"schedules": [
{
"id": 1307654,
"name": "s2",
"budget": 2000,
"startDateStr": "2020-09-29T05:00:00Z",
"endDateStr": "2020-12-29T05:59:59Z",
"dailyBudgetType": "AUTO_ALLOCATED"
},
{
"id": 1307653,
"name": "s1",
"budget": 1000,
"dailyBudget": 150,
"startDateStr": "2020-08-11T05:00:00Z",
"endDateStr": "2020-09-29T04:59:59Z",
"dailyBudgetType": "SPECIFIED_AMOUNT"
}
],
"feeList": [
{
"id": 12584,
"name": "amc",
"fee": 0.86,
"typeName": "AD_SERVING"
}
],
"conversionList": [
{
"id": 7386,
"lineId": 630162,
"beaconId": 15776560,
"acceptViewThrough": true,
"clickWindow": 4,
"viewWindow": 2,
"name": "test rule 1",
"viewBeaconValueDiscount": 0,
"beaconValuePc": 1.05,
"clickWindowUnitType": "DAY",
"viewWindowUnitType": "HOUR"
}
]
},
{
"id": 630161,
"name": "display-line-multi-budget-12",
"orderId": 462137,
"bidPrice": 1,
"goalAmount": 1.34,
"maxGoal": 1.34,
"marginGoal": 25,
"billingPrice": 1,
"completionThreshold": 0,
"isNativeEnabled": false,
"status": "PAUSED",
"pacingModeType": "EVEN",
"mediaType": "DISPLAY",
"goalModeType": "SOFT",
"goalType": "CPC",
"billingMethodType": "MARGIN",
"marginType": "TOTAL_BUDGET",
"budgetType": "CURRENCY",
"schedules": [
{
"id": 1307652,
"name": "s2",
"budget": 2000,
"startDateStr": "2020-09-29T05:00:00Z",
"endDateStr": "2020-12-29T05:59:59Z",
"dailyBudgetType": "AUTO_ALLOCATED"
},
{
"id": 1307651,
"name": "s1",
"budget": 1000,
"dailyBudget": 150,
"startDateStr": "2020-08-11T05:00:00Z",
"endDateStr": "2020-09-29T04:59:59Z",
"dailyBudgetType": "SPECIFIED_AMOUNT"
}
],
"feeList": [],
"conversionList": []
}
],
"errors": null,
"timeStamp": "2020-07-14T02:28:12.227Z"
}
Create Line¶
Create a new line.
POST /traffic/lines/
To create a display line, specify
DISPLAY
as the line’smediaType
value.To create a video line, specify
VIDEO
as the line’smediaType
value.To create an audio line, specify
AUDIO
as the line’smediaType
value.
Parameters¶
All fields are specified in the body of application/json payload.
Example Request URL¶
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 |
---|---|---|
|
|
|
|
|
|
|
|
|
Example Request Body¶
{
"name": "display-line-ocpm-1",
"orderId": 462137,
"status": "PAUSED",
"mediaType": "DISPLAY",
"pacingModeType": "EVEN",
"budgetType": "CURRENCY",
"goalType": "CPC",
"billingMethodType": "MARGIN",
"billingPrice": 2,
"marginType": "TOTAL_BUDGET",
"bidPrice": 1,
"maxGoal": 1,
"marginGoal": 25,
"goalAmount": 1,
"isNativeEnabled": false,
"completionThreshold": 0,
"schedules": [
{
"startDateStr": "2020-09-29",
"endDateStr": "2020-12-28",
"budget": 2000,
"dailyBudgetType": "AUTO_ALLOCATED"
}
]
}
Example: Create oCPC Display Line¶
To create a DISPLAY
line with oCPC
goal type, refer to the table and payload below.
Field |
Value |
Type |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example Request Body¶
{
"name": "display-line-ocpc-1",
"orderId": 462137,
"mediaType": "DISPLAY",
"billingMethodType": "CPM_PRICE",
"billingPrice": 1,
"marginType": "TOTAL_BUDGET",
"bidPrice": 1,
"goalType": "OCPC",
"maxGoal": 1.1,
"marginGoal": 25,
"status": "ACTIVE",
"goalAmount": 1.1,
"pacingModeType": "EVEN",
"isNativeEnabled": false,
"completionThreshold": 0,
"schedules": [
{
"startDateStr": "2020-08-11",
"endDateStr": "2020-09-28",
"budget": 1000,
"dailyBudget": 150,
"dailyBudgetType": "SPECIFIED_AMOUNT"
}
]
}
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 |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example Request Body¶
{
"name": "video-line-cpcv-single-budget-1",
"orderId": 462137,
"status": "ACTIVE",
"mediaType": "VIDEO",
"pacingModeType": "EVEN",
"budgetType": "CURRENCY",
"goalType": "CPCV",
"billingMethodType": "CPCV",
"billingPrice": 1,
"marginType": "TOTAL_BUDGET",
"bidPrice": 1,
"maxGoal": 1,
"marginGoal": 25,
"goalAmount": 1,
"isNativeEnabled": false,
"completionThreshold": 0,
"schedules": [
{
"startDateStr": "2020-08-11",
"endDateStr": "2021-01-28",
"budget": 1000,
"dailyBudget": 150,
"dailyBudgetType": "SPECIFIED_AMOUNT"
}
]
}
Example: Create Line with Currency Daily Budget & Single Schedule¶
To create a DISPLAY
line with a specified daily budget and a single budget schedule, refer to the table and payload below.
Field |
Value |
Type |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example Request Body¶
{
"name": "display-line-single-budget-1",
"orderId": 462137,
"status": "PAUSED",
"mediaType": "DISPLAY",
"budgetType": "CURRENCY",
"goalType": "CPC",
"billingMethodType": "MARGIN",
"billingPrice": 1,
"marginType": "TOTAL_BUDGET",
"pacingModeType": "EVEN",
"bidPrice": 1,
"marginGoal": 25,
"goalAmount": 1.34,
"isNativeEnabled": false,
"completionThreshold": 0,
"schedules": [
{
"startDateStr": "2020-08-11",
"endDateStr": "2021-01-28",
"budget": 1000,
"dailyBudget": 150,
"dailyBudgetType": "SPECIFIED_AMOUNT"
}
],
"conversionList": [
{
"beaconId": 15776560,
"acceptViewThrough": true,
"clickWindow": 4,
"viewWindow": 2,
"viewBeaconValueDiscount": 0,
"beaconValuePc": 1.05,
"clickWindowUnitType": "DAY",
"viewWindowUnitType": "HOUR"
}
],
"feeList": [
{
"typeName": "AD_SERVING",
"name": "amc",
"fee": 0.86
}
]
}
Example: Create Impression Budget Video Line¶
To create a VIDEO
line with auto allocated Impression-based budget, refer to the table and payload below.
Field |
Value |
Type |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example Request Body¶
{
"name": "video-line-single-budget-imp-6",
"orderId": 462137,
"bidPrice": 9,
"marginGoal": 25,
"billingPrice": 9,
"isNativeEnabled": false,
"completionThreshold": 60,
"pacingAcceleration": 0,
"status": "ACTIVE",
"pacingModeType": "EVEN",
"mediaType": "VIDEO",
"goalType": "COMPLETION_HARD_THRESHOLD",
"goalAmount": 1.1,
"maxGoal": 1.15,
"budgetType": "IMPRESSION",
"billingMethodType": "CPM_PRICE",
"marginType": "TOTAL_BUDGET",
"schedules": [
{
"startDateStr": "2020-08-11",
"endDateStr": "2021-01-28",
"impBudget": 7111,
"dailyBudgetType": "AUTO_ALLOCATED"
}
]
}
Example: Create Multiple Budget Line¶
To create a line with multiple budgets, refer to the payload below.
Example Request Body¶
{
"name": "display-line-multi-budget-1",
"orderId": 462137,
"status": "PAUSED",
"mediaType": "DISPLAY",
"budgetType": "CURRENCY",
"goalType": "CPC",
"billingMethodType": "MARGIN",
"billingPrice": 1,
"marginType": "TOTAL_BUDGET",
"pacingModeType": "EVEN",
"bidPrice": 1,
"marginGoal": 25,
"goalAmount": 1.34,
"isNativeEnabled": false,
"completionThreshold": 0,
"schedules": [
{
"name": "s1",
"startDateStr": "2020-08-11",
"endDateStr": "2020-09-28",
"budget": 1000,
"dailyBudget": 150,
"dailyBudgetType": "SPECIFIED_AMOUNT"
},
{
"name": "s2",
"startDateStr": "2020-09-29",
"endDateStr": "2020-12-28",
"budget": 2000,
"dailyBudgetType": "AUTO_ALLOCATED"
}
]
}
Example: Create Line with AppMarketing Objective¶
To create a line with CPI
goal and app marketing objective, refer to the table and payload below. Note that at least one conversion pixel is required when goal type is CPI
.
Field |
Value |
Type |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Example Request Body¶
{
"name": "test-video5599",
"orderId": 312515,
"status": "ACTIVE",
"mediaType": "VIDEO",
"pacingModeType": "EVEN",
"budgetType": "CURRENCY",
"goalType": "CPI",
"billingMethodType": "CPCV",
"dailyBudgetType": "SPECIFIED_AMOUNT",
"dailyBudget": 1.25,
"billingPrice": 1,
"marginType": "TOTAL_BUDGET",
"bidPrice": 1,
"maxGoal": 1,
"marginGoal": 25,
"goalAmount": 1,
"isNativeEnabled": false,
"completionThreshold": 0,
"schedules": [
{
"startDateStr": "2020-08-11",
"endDateStr": "2021-01-28",
"impBudget": 7111,
"dailyBudgetType": "AUTO_ALLOCATED"
}
],
"appMarketingObjective": "RE_ENGAGEMENT",
"appUrl": "https://apps.apple.com/us/app/colorsnap-visualizer-iphone/id316256242&locale=en-us",
"appLocale": "en-us",
"conversionList": [
{
"beaconId": 15776560,
"acceptViewThrough": true,
"clickWindow": 4,
"viewWindow": 2,
"viewBeaconValueDiscount": 0,
"beaconValuePc": 1.05,
"clickWindowUnitType": "DAY",
"viewWindowUnitType": "HOUR"
}
]
}
Update Line¶
Update an existing line.
PUT /traffic/lines/{id}
Partial updates are supported (with the exception of feeList
, see note below); values of supported fields which are not in the payload will remain unchanged.
Note
When updating variable costs using feeList
, any existing entries will be removed automatically unless they included in the payload.
Parameters¶
The Line id is specified in the url path. All other fields are specified in the body of the application/json payload.
Example: Activate Paused Line¶
The following payload shows how to change the line status from PAUSED
to ACTIVE
.
Example Request Body¶
{
"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 Body¶
{
"schedules": [
{
"startDateStr": "2020-08-11",
"endDateStr": "2021-01-31",
"impBudget": 10000
}
]
}
Example: Update Line with Conversion Pixel¶
The following payload shows how to add a conversion pixel to an existing line.
Example Request Body¶
{
"conversionList": [
{
"lineId": 355775,
"beaconId": 762,
"acceptViewThrough": true,
"viewWindow": 2,
"clickWindow": 4,
"clickWindowUnitType": "DAY",
"viewWindowUnitType": "HOUR",
"beaconValuePc": 1.2
}
]
}
Example: Remove an Existing Conversion Pixel¶
The following payload shows how to remove an existing conversion pixel from a line.
An existing conversion pixel can be removed by setting lineId
to 0
.
Example Request Body¶
{
"conversionList": [
{
"id": 144856,
"lineId": 0,
"beaconId": 762
}
]
}
Delete Lines¶
The DSP Traffic API does not support deletion of lines.