This is a preview and draft version of the Proposed Placement API v4. This document is subject to change as the implementation is completed, and will be updated accordingly.
Introduction
Proposal capability in MRM is enabled through a Network Function. Please contact your Account Manager if you are interested in this functionality.** A Proposed Placement acts as a proposed Sale, or a collection of Ad Units that share sales specifications, such as flight dates and content targeting. Business rules for a proposed sale can be configured via a proposed placement.
You can use this API to accomplish the following tasks:
Time when the proposed placement was most recently updated.
No
No
Placement Schedule Attributes - Child Attributes
The date/time format should follow the ISO-8061 format in UTC timezone for create requests, update requests and get responses; for example: 2013-09-04T10:59:00Z.
Name
Type
Description
Creatable?
Updatable?
Notes
start_time
DateTime
The start time of the placement
Yes
Yes
end_time
DateTime
The end time of the placement
Yes
Yes
If budget=evergreen with ongoing=true, end_time is optional and return blank
Demographic / CPx / SOI is controlled by network functions
currency
Float
Yes
Yes
Valid and required when budget_model = CURRENCY_TARGET
impression
Integer
Yes
Yes
Valid and required when budget_model = IMPRESSION_TARGET
volume_cap
Integer
Yes
Yes
Valid when budget_model = ALL_IMPRESSION.
volume_cap_type
['NO_VOLUME_CAP', 'CUSTOM_VOLUME_CAP']
Yes
Yes
when volume_cap_type = 'NO_VOLUME_CAP' ignore volume_cap
estimated_impression_goal
Integer
Yes
Yes
Valid when budget_model = 'ALL_IMPRESSION', 'SOV', 'SOP', 'SOI
share_percentage
Float
Yes
Yes
Valid and required when budget_model = SOV, SOP, SOI
ongoing
Boolean
Yes
Yes
Valid when budget_model = EVERGREEN; Set as 'False' by default. When set as "True", the placement end_time will be cleared
on_target_currency
Float
Yes
Yes
Valid and required when budget_model = DEMOGRAPHIC_CURRENCY_TARGET and CUSTOM_CURRENCY_TARGET
gross_currency_cap
Float
Yes
Yes
Valid and required when budget_model = DEMOGRAPHIC_CURRENCY_TARGET and CUSTOM_CURRENCY_TARGET
on_target_impressions
Integer
Yes
Yes
Valid and required when budget_model = DEMOGRAPHIC_IMPRESSION_TARGET
event_goal
Integer
Yes
Yes
Valid and required when budget_model = CUSTOM_EVENT_TARGET
gross_impression_cap
Integer
Yes
Yes
Valid and required when budget_model = DEMOGRAPHIC_IMPRESSION_TARGET and CUSTOM_EVENT_TARGET
data_source
['NIELSEN']
Yes
Yes
Valid and required when budget_model = DEMOGRAPHIC_IMPRESSION_TARGET/DEMOGRAPHIC_CURRENCY_TARGET
demographic_ids
Set of Demographic FW ID
The ID of target demographic
Yes
Yes
Valid and required when budget_model = DEMOGRAPHIC_IMPRESSION_TARGET/DEMOGRAPHIC_CURRENCY_TARGET. Should refer to the demographics ID mapping file.
billable_event_id
FW_ID
Yes
Yes
Valid and required when budget_model = CUSTOM_EVENT_TARGET and CUSTOM_CURRENCY_TARGET
over_delivery
Float
Yes
Yes
Valid when budget_model is CURRENCY_TARGET, IMPRESSION_TARGET, DEMOGRAPHIC_IMPRESSION_TARGET, DEMOGRAPHIC_CURRENCY_TARGET, CUSTOM_EVENT_TARGET and CUSTOM_CURRENCY_TARGET. In GET request, when over_delivery_type = CUSTOM, return user defined over_delivery value. When over_delivery_type = DEFAULT, this refers to the network default over delivery value.
over_delivery_type
['CUSTOM', 'DEFAULT']
Yes
Yes
In Create/Update request, when over_delivery_type = 'DEFAULT', we'll ignore any given over_delivery.
Placement Ad Product Attributes - Child Attributes
Valid when budget_model = DEMOGRAPHIC_IMPRESSION_TARGET and DEMOGRAPHIC_CURRENCY_TARGET; The default value is based on the first parameter of the network function RATINGS_BASED_SELLING
demographic_impression_steering_enabled
Boolean
Enable demographic impression steering
Yes
Yes
Valid when budget_model = DEMOGRAPHIC_IMPRESSION_TARGET and DEMOGRAPHIC_CURRENCY_TARGET; The default value is based on the third parameter of the network function RATINGS_BASED_SELLING
level_to_optimize_for_profit
[ 'NONE', 'LOWEST', 'MODERATE', 'HIGHEST' ]
Level To Optimize For Profit
Yes
Yes
Controlled by network function MARGIN_BASED_DELIVERY_CONFIG. The default value is based on the parameter of the network function MARGIN_BASED_DELIVERY_CONFIG
Controlled by network function MARGIN_BASED_DELIVERY_CONFIG. Be able to set excess_inventory_precondition only when 'Level To Optimize For Profit' is 'NONE' and 'Excess Inventory' not in ['0%', 'NETWORK_DEFAULT']. If a request is sent without the node or the node is empty, it will be set as “UNLIMITED” by default if excess inventory is “0%”, and set as “0” by default if excess inventory is set as greater than 0.
Valid and required when budget_model = CURRENCY_TARGET, IMPRESSION_TARGET, DEMOGRAPHIC_IMPRESSION_TARGET or DEMOGRAPHIC_CURRENCY_TARGET, CUSTOM_EVENT_TARGET and CUSTOM_CURRENCY_TARGET. When budget_model = EVERGREEN, can mode only be BELOW_PAYING_ADS and valud = -10
Valid and required when budget_model = CURRENCY_TARGET, IMPRESSION_TARGET, DEMOGRAPHIC_IMPRESSION_TARGET or DEMOGRAPHIC_CURRENCY_TARGET, CUSTOM_EVENT_TARGET and CUSTOM_CURRENCY_TARGET When budget_model = EVERGREEN, can mode only be BELOW_PAYING_ADS and valud = -10
amongst_by
[ 'ABSOLUTE_RANK', 'CPM' ]
Yes
Yes
Valid when mode = AMONGST_PAYING_ADS; Set 'CPM' by default 'ABSOLUTE_RANK' is controlled by NUM_COMPETING_AD_SCORE
The Industries, Advertisers, Brands, Resellers, Campaigns, IOs, or Placements that are excluded from returning within the scope defined in scope_of_exclusivity.
The Industries, Advertisers, Brands, Resellers, Campaigns, IOs, or Placements that are exempt from returning within the scope defined in scope_of_exclusivity.
The combination of relations (AND, OR) separated by commas; The number of relation_between_sets must equal to the number of sets minus 1; If there are 3 sets and a remaining set, the last relation_between_sets must be OR.
Content Set Attributes - Child Attributes
Name
Type
Creatable?
Updatable?
Notes
name
String
No
No
Return 'Set1', 'Set2', 'Set3', 'Remaining Items'
relation_in_set
['AND', 'OR' ]
Yes
Yes
For the 4th set (Remaining Items), the relation_in_set much be OR.
If there are multiple sets, the relationship within a set can only be "OR"; If there is only one set with multiple key values, the relationship is required and can be "OR" or "AND"
The combination of relations (AND, OR) separated by commas; The number of relation_between_sets must equal to the number of sets minus 1; If there are 3 sets and a remaining set, the last relation_between_sets must be OR.
Audience Set Attributes - Child Attributes
Name
Type
Creatable?
Updatable?
Notes
name
String
No
No
Return 'Set1', 'Set2', 'Set3', 'Remaining Items'
relation_in_set
[ 'AND', 'OR' ]
Yes
Yes
For the 4th set (Remaining Items), the relation_in_set much be OR.
