Introduction

A placement is a Sale, or a collection of Ad Units that shares sales specifications like flight dates and content targeting.

The placement is where most business rules, sales terms, and actions are configured for a particular sale. You can execute specific tasks on placements as well. MRM optimizes and analyzes the buying slots for ad placement.

You can use this API to:

• View placements
• Create placements
• List placements
• Edit placements

Related Documentation

Refer to the following documentation for more information about FreeWheel products and APIs:

• Getting Started with the FreeWheel APIs
• Placements - MRM User Guide

Resources

URI(s)

The Placement API v3 identifies two Uniform Resource Identifiers (URIs):

Targeting Marketplace Platform Content

Placement API V3 supports Run of Marketplace Network (ROMN). By targeting ROMN, you can target all content acquired through the Marketplace Platform.

Placement API Attributes

Attributes represent and describe data associated with an object, in this case, the Placement object. Attributes are organized in sets, which determine the fields available during data entry, and the values you can see.

📘

Use Placement API Attributes in conjunction with Placement API methods to accomplish your ad tech objectives.

Basic Attributes

Basic attributes describe fundamental properties of a placement. These attributes identify the name, ID, insertion order, and other details of the placement.

The following parameters are all included in basic GET requests.

The following parameters are all included in basic GET requests.

Create Basic Attributes

The following sample code block shows you how to create basic attributes for a placement.

<placement>
  <insertion_order_id>1000</insertion_order_id>
  <name>my placement</name>
  <description>some description</description>
  <instruction>my instruction</instruction>
  <placement_type>MAKE_GOOD</placement_type>
  <enable_canoe>false</enable_canoe>
   <external_id>test external id</external_id>
</placement>

Clear Basic Attributes

The following sample code block shows you how to clear basic attributes for a placement.

📘

Note

Nodes name, buy_type_id, placement_type and enable_canoe cannot be cleared.

<placement>
  <description></description>
  <instruction></instruction>
  <property_id></property_id>
  <adjust_from_balance></adjust_from_balance>
  <external_id></external_id>
</placement>

GET Basic Attributes

The following example code block shows you how to get basic attributes for a placement.

<placement>
  <id>100000</id>
  <insertion_order_id>1000</insertion_order_id>
  <name>my placement</name>
  <description>some description</description>
  <placement_type>NORMAL</placement_type>
  <instruction>my instruction</instruction>
  <buy_type_id>10001</buy_type_id>
  <property_id>10000</property_id>
</placement>

Schedule Attributes - Child Attributes of Basic Attributes

Schedule attributes provide scheduling details.

📘

Note

The schedule data should be grouped under the schedule node. See a list of valid time zones.

The date/time format should follow the ISO 8061 format in local timezone for create requests, update requests and get responses; for example: 2013-09-04T10:59.

📘

Note

ISO 8061 in UTC is not supported. Note:.

The system counts time only in minutes: do not input time in seconds. The start_time automatically starts at the first second of the specified minute. The end_time counts until the last second of the specified minute. Time format of start_time and end_time in the Get response follows ISO 8061 format in the local timezone

📘

Note

The schedule of a placement cannot be cleared via API V3.

Price Attributes - Child Attributes of Basic Attributes

All price data should be grouped under the 'price' node.

📘

Notes

• The Price and Budget Model widget is set as blank when the price is being cleared.

• When the budget is evergreen, FreeWheel returns an empty price node in the response.

Budget Attributes - Child Attributes of Basic Attributes

All budget data should be grouped under the 'budget' node.

📘

Note

When the budget model is CURRENCY_TARGET, IMPRESSION_TARGET, DEMOGRAPHIC_IMPRESSION_TARGET or DEMOGRAPHIC_CURRENCY_TARGET, and over_delivery_value is the network default value, the over_delivery_value returns blank.

Delivery Attributes - Child Attributes of Basic Attributes

The delivery data should be grouped under the 'delivery' node.

Pacing_point Attributes - Child Attributes of Delivery Attributes

Advanced Identity Level Frequency Capping

Advanced Identity level frequency capping (the advanced_fc_identity_level node) ensures that the same household does not get inundated with the ads from the same placement. When a frequency cap is set with an advanced identity level, the ad server restricts the maximum number of times the ad units in a placement can be served to a viewer during a specific amount of time or content.

Frequency_cap Attributes - Child Attributes of Delivery Attributes

📘

Note

The advanced_fc_identity_level attribute represents an optional feature that must be turned on by your Program Manager. If the feature has not been activated in your network but the node is submitted, the node is ignored and is set by default to Identifier from Request (the normal identity level).

Override Attributes - Child Attributes of Basic Attributes

The override data should be grouped under the override node. When a placement's budget_model is SOP/SOI, override cannot be set.

Content Targeting Attributes - Child Attributes of Basic Attributes

The content targeting data is grouped under the 'content_targeting' node.

• Mandatory: One of inclusion exists from ‘network_items’, ‘standard_attributes’, ‘inventory_packages’, ‘ron’

Advanced Combination Include - Child Attributes

Set - Child Attributes

Standard Attributes - Child Attributes

Network Items – Child Attributes

Standard Attributes – Child Attributes

Standard Attributes are only valid for Marketplace clients. Contact FreeWheel if you would
like to enable Marketplace.

All platform standard attributes data should be grouped under standard_attributes in the platform_targeting node.

Standard Attributes include/exclude – Standard Attribute Child Attributes

Standard Attributes are only valid for Marketplace clients. Contact FreeWheel if you would
like to enable Marketplace.

Inventory Packages – Child Attributes

Inventory Packages only valid for Marketplace clients. Contact FreeWheel if you would like to enable Marketplace.

Neither of these attributes is mandatory.

Inventory Package include – Inventory Package Child Attributes

inventory Package only valid for Marketplace clients. Contact FreeWheel if you would like to enable Marketplace.

📘

Note

Only ACTIVE Inventory Packages are targetable.

RON – Child Attributes

Standard Attributes are only valid for Marketplace clients. Contact FreeWheel if you would
like to enable Marketplace.

Advanced Content Targeting Attributes - Child Attributes of Basic Attributes

• Mandatory: One of inclusion exists from ‘network_items’, ‘standard_attributes’, ‘inventory_packages’, ‘ron’

Content Package Targeting Attributes - Child Attributes of Basic Attributes

If using Content Packages, you cannot use the include/exclude set level of granularity

Exclusivity Attributes - Child Attributes of Basic Attributes

The exclusivity data should be grouped under the 'exclusivity' node.

Scope of Exclusivity Attributes - Child Attributes of Exclusivity Attributes

Excluded Item Child Node Attributes - Child Attributes of Scope of Exclusivity Attributes

Exempt Item Child Node Attributes - Child Attributes of Scope of Exclusivity Attributes

Custom Targeting Attributes - Child Attributes of Basic Attributes

The custom targeting data should be grouped under 'custom_targeting'.

Custom Targeting Set Attributes - Child Attributes of Custom Targeting Attributes

Daypart Targeting Attributes - Child Attributes of Basic Attributes

The daypart targeting data should be grouped under 'daypart_targeting'.

Daypart Part Attributes - Child Attributes of Daypart Targeting Attributes

Geography Targeting Attributes - Child Attributes of Basic Attributes

The geography targeting data should be grouped under the <geography_targeting> node. This node features support for both including and excluding geography items.

Geography Set Attributes - Child Attributes of Geography Targeting Attributes

The attributes below are included in GET requests.

Ad Product Attributes - Child Attributes of Basic Attributes

The ad product data should be grouped under the 'ad_product' node.

Ad Unit Node Attributes - Child Attributes of Ad Product Attributes

Linking Scenario Attributes - Child Attributes of Ad Product Attributes

Custom Set Attributes - Child Attributes of Ad Product Attributes

📘

Notes

• The "exclude from invoice" and "accounting price" attributes (the latter available for "Make Good" placements) could be cleared from an Ad Unit when updating the Ad Product via API V3 much like they would in the UI.

• Ad Product of a placement cannot be cleared via API V3.

• Ad units in an ad package will be shown as individual ad units; no ad package IDs are returned in the Get response. Status is returned for MRM only networks.

Normal Audience Targeting Attributes - Child Attributes of Basic Attributes

The audience targeting data should be grouped under the 'audience_targeting' node.

Advanced Audience Targeting Attributes - Child Attributes of Basic Attributes

The audience targeting data should be grouped under the 'audience_targeting' node.

Restrict Delivery to Campaign Tags Attributes - Child Attribute to Basic Attributes

Does not support clear on campaign tags.

Soft Reserve Attributes - Child Attributes to Basic Attributes

All soft reserve data should be grouped under the 'soft_reserve' node.

Does not support clear on soft reserve

Industry Attributes - Child Attributes to Basic Attributes

All industry data should be grouped under the 'industry' node. To see the public list of valid industry IDs, click API Resources. Contact FreeWheel if you would like to get IDs for your network's custom Industry Groups.

Platform Targeting Attributes - Child Attributes of Basic Attributes

All platform targeting data should be grouped under the 'platform_targeting' node.

📘

Note

The standard_attributes node conflicts with the device, os, browser, and package nodes. If the request passes through any of them with the node standard_attributes, an error is returned an error.

Standard Attributes–Child Attributes

Standard Attributes are only valid for Marketplace clients. Contact FreeWheel if you would like to enable Marketplace.

Alert Attributes - Child Attributes of Basic Attributes

All alert data should be grouped under the 'alert' node. Alert only support for MRM-only placement, and it's get-only.

The following attributes are used by MRM only.

Create/Update Alert Info is not supported.
Create Alert Info is not supported.

Cost Attributes - Child Attributes of Basic Attributes

The cost data should be grouped under the 'cost' node.

📘

Note

Cost is an optional feature that must be turned on by your Program Manager

Create/Update Cost is not supported.
Clear Cost is not supported.

Premiums Attributes - Child Attributes of Basic Attributes

The premiums data should be grouped under the 'premiums' node.

📘

Note

Premiums is an optional feature enabled only for Networks with Sales Proposal enabled.

Placement Template Label Attributes - Child Attributes of Basic Attributes

The placement template label data should be grouped under the 'placement_template_label' node.

📘

Note

The Placement template label is an optional feature that must be turned on by your Program Manager.

Create/Update Placement Template Label is not supported.
Clear Placement Template Label is not supported.

Ratings Based Planning (RBP) Advanced Attributes

All of the parameters below are included in GET requests.

Marketplace Supply Source Attributes - Child Attributes

Inventory Order - Child Attributes of Marketplace Supply Source Attribute

Inventory Split Order - Child Attributes of Marketplace Supply Source Attribute

Supply Source Package - Child Attributes of Marketplace Supply Source Attribute

Seller - Child Attribute of Marketplace Supply Source Attribute

ID - Child Attributes of Inventory Order, Inventory Split Order, SSP Inventory Order, Supply Source Package and Seller Attributes

Yield Optimization Attributes - Child Attributes

Yield Optimization is available only to networks enabled with Yield Optimization capability. Contact FreeWheel to enable this functionality.

🚧

Note

If a Yield Optimization parent attribute is set to INHERIT or IGNORE, passing empty ID child attributes will result in an error. This occurs because the system interprets empty pairs as ID value 0.

Volume Cap Optimization IDs Attributes - Child Attributes

Volume Cap Optimization IDs is only available when placement yield optimization volume cap configurations is set to OVERRIDE.

Inventory Prioritization Optimization IDs Attributes - Child Attributes

Inventory Prioritization Optimization IDs is only available when placement yield optimization inventory prioritization configurations is set to OVERRIDE.

Distribution Optimization IDs Attributes - Child Attributes

Distribution Optimization IDs are only available when placement yield optimization distribution configurations are set to OVERRIDE.

Inventory Value Distribution Optimization IDs Attributes - Child Attributes

Inventory Value Distribution Optimization IDs is only available when placement inventory value
distribution configurations is set to OVERRIDE.

ISP Targeting Attributes - Child Attributes of Basic Attributes

ISP Targeting is available in the <isp_targeting> node which contains a node with the ID of the ISP.