The Yield Optimization Volume Cap API V4 allows you to perform a series of interactive operations on the Volume Cap type of Yield Optimization rules.

📘
Note
Yield Optimization Volume Cap API V4 functionality is only available for Marketplace users.

You can use the Yield Optimization Volume Cap API V4 to:

Create a new Yield Optimization Volume Cap rule;
Update an existing Yield Optimization Volume Cap rule, including the activation and deactivation;
Retrieve a list of Yield Optimization Volume Cap rules of your current network with basic attributes returned and query the list by id, name, application_scope, demand_type, and status;
Retrieve full attributes of an individual Yield Optimization Volume Cap rule;

GENERAL RESOURCE URIS

Type	URI
Production Instance	`https://api.freewheel.tv/services/v4/yield_optimization/volume_caps?{param1}={query1}&...`
Staging Instance	`https://api.stg.freewheel.tv/services/v4/yield_optimization/volume_caps?{param1}={query1}&...`

BASIC ATTRIBUTES

Name	Type	Description	Get Only?	Notes
id	FW_ID	The ID of the yield optimization volume cap rule.	Yes
network_id	FW_ID	The ID of the network which the yield optimization volume cap rule belongs to.	Yes
name	String	The name of the yield optimization volume cap rule.		The maximum length of characters is 255
description	String	The description of the yield optimization volume cap rule.		The maximum length of characters is 500.
start_time	Time	The start time of the yield optimization volume cap rule.		The value must be later than current time.
end_time	Time	The end time of the yield optimization volume cap rule. It would return empty when end_time is ongoing.		The value must be later than start time and current time. If it's an ongoing order, the end_time would be empty.
status	Enum	The status of the yield optimization volume cap rule. Valid values: - ACTIVE - INACTIVE -NOT_START -EXPIRED
goal_type	Enum	The cap model of a yield optimization volume cap rule. Valid values: - VOLUME_CAP
supplies_and_optimization_goals	Array of the set of supplies_and_optimization_goal	The supplies and optimization goals of a multiple-mode yield optimization volume cap rule allow a flexible way to configure the supply scope in expressions composed of multiple dimensions.		Only be valid when supply mode is MULTIPLE The maximum number of supplies_and_optimization_goal sets is 20.
application_scope	Enum	The demand application scope of a yield optimization volume cap rule. It determines whether the rule applies to a specific demand object or the whole network. Valid values: - GLOBAL - DEMAND_TYPE_SPECIFIC		Each network can only have one GLOBAL volume cap rule.
demand_type	Enum	The demand type that the volume cap rule takes effect on. Valid values: - PLACEMENT - MARKETPLACE_INVENTORY_ORDER - PROGRAMMATIC_GUARANTEED_DEAL		MARKETPLACE_INVENTORY_ORDER is only valid for Marketplace sellers. PROGRAMMATIC_GUARANTEED_DEAL is only valid for Programmatic customers.
risk_level	Enum	The risk level of yield optimization distribution. Valid values: - SAFE - LIGHT_RISK - MEDIUM_RISK - HEAVY_RISK - IGNORE_GOAL

Supplies and Optimization Goal - Child Attributes

Name	Type	Description	Notes
expression_and_goal_id	Integer	The supply and optimization goal id of an optimization goal.	The ID will be generated the first time push a new goal; If the user would like to update an existing optimization goal attribute, please ensure to pass the corresponding expression_and_goal_id in the request. Otherwise a new goal would be created.
expression	Set	The supply scope expressions are composed of multiple dimensions to which the rule would apply.
cap_value	Integer	The cap value of a multiple volume cap YO rule for one individual optimization goal. The value must be between 0 and 100.
label	String	The label of an optimization goal.	The maximum length of this field is 255.

Expression - Child Attributes

Name	Type	Description	Notes
relation_between_statements	Enum	The operator of an expression indicates the logical relationship across all relations/statements within the current optimization goal. Valid values: AND, OR
statements	Array of Statement	Each statement contains multiple sets composed of corresponding inclusive and exclusive items.

Statements - Child Attributes

Name	Type	Description	Notes
relation_between_sets	Enum	The operator of a relation/statement indicates the logical relationship across all sets within the current relation. Valid values: AND, OR
sets	Array of Set	Each set has its own inclusive and exclusive items.

Set - Child Attributes

Name	Type	Description	Notes
item_inclusion_exclusion_type	Enum	It indicates that the items below will be inclusive or exclusive items. If this field is true, it means EXCLUDE the items. If the field is false, it means INCLUDE the items
items	Array of Item	Inclusive or exclusive items of each individual set of an optimization goal.

Item - Child Attributes

Name	Type	Description	Get Only?	Notes
type	Enum	The type of items to be selected into relation/statement sets. Valid values are ENDPOINT_OWNER, ENDPOINT_NAME,COUNTRY, STATE, DMA, POSTAL_CODE, STREAM_MODE, PROGRAMMER, BRAND, CHANNEL, DEVICE, ENVIRONMENT, OS, GENRE, LANGUAGE, TV_RATING, DURATION, DAYPART, INVENTORY_ORDER, INVENTORY_PACKAGE		INVENTORY_ORDER is only valid for Marketplace buyers. INVENTORY_PACKAGE Is only valid for Marketplace customers.
id	FW_ID	The id of the included/excluded item.

Demand - Child Attributes

Name	Type	Description	Get Only?	Notes
demand_id	FW_ID	The ID of the demand object that the YO rule applied to.	Yes
demand_name	String	The name of the demand object that the YO rule applied to.	Yes
public_id	String	The external_deal_id of the programmatic deal that the YO rule applies to.	Yes	valid only when demand_type = PROGRAMMATIC_GUARANTEED_DEAL

📘Note

GENERAL RESOURCE URIS

BASIC ATTRIBUTES

Supplies and Optimization Goal - Child Attributes

Expression - Child Attributes

Statements - Child Attributes

Set - Child Attributes

Item - Child Attributes

Demand - Child Attributes

📘
Note