Introduction

A placement is a Sale, or a collection of Ad Units that share sales specifications, such as flight dates and content targeting. The placement is where most business rules for a particular sale are configured. Settings configure sales terms and actions execute specific tasks on placements. The MRM product optimizes and analyzes the buying slots for ad placement.

Version 3 of the Placement API allows users to view, create, list, and edit Placements. This version of the API uses validations that were introduced with UIF.

You can use this API to accomplish the following tasks:

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

Related Documentation

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

• API Documentation
• RPM User Manual
• Placements - MRM User Guide

Resources

URI(s)

The Placement API v3 identifies two Uniform Resource Identifiers (URIs), a production instance and a staging instance identified in the following table:

Placement API Attributes

Attributes represent and describe data associated with an object, in this case the Placement object. Attributes are organized in sets. The attribute set determines the fields that are available during data entry, and the values that appear to the client. 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 attributes are only available for Networks with Sales Proposal enabled:

The following example 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>
  <!-- RPM only attributes start-->
  <buy_type_id>10001</buy_type_id>
  <property_id>10002</property_id>
  <adjust_from_balance>DEFERRED_REVENUE</adjust_from_balance>
  <external_infos>
   <external_info>
    <external_system_id>ID1</external_system_id>
    <external_id>xxx</external_id>
    <primary>true</primary>
   </external_info>
   <external_info>
    <external_system_id>ID2</external_system_id>
    <external_id>xxx</external_id>
    <primary>false</primary>
   </external_info>
  </external_infos>
  <!-- RPM only attributes end-->
  <!-- MRM only attributes start-->
  <external_id>test external id</external_id>
  <!-- MRM only attributes end-->
</placement>

The following example 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>
  <!-- RPM only attributes start-->
  <external_info></external_info>
  <property_id></property_id>
  <adjust_from_balance></adjust_from_balance>
  <!-- RPM only attributes end-->
  <!-- MRM only attributes start-->
  <external_id></external_id>
  <!-- MRM only attributes end-->
</placement>

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>
  <enable_canoe>false</enable_canoe>
  <external_infos>
   <external_info>
    <external_system_id>ID1</external_system_id>
    <external_id>xxx</external_id>
    <primary>true</primary>
   </external_info>
   <external_info>
    <external_system_id>ID2</external_system_id>
    <external_id>xxx</external_id>
    <primary>false</primary>
   </external_info>
  </external_infos>
</placement>

External Infos Attributes - Child Attributes of Basic Attributes

External Infos attributes provide external system details.

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 that ISO 8061 in UTC is not supported.

The system counts time only in minutes; please do not input time in seconds. The start_time will automatically start at the first second of the specified minute. The end_time will count until the last second of the specified minute.

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

Note: Time format of start_time and end_time in the Get response follows ISO 8061 format in local timezone.

Price Attributes - Child Attributes of Basic Attributes

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

Price Attribute Definitions

Note: The Price and Budget Model widget will be set as blank when clearing the price.

Note: When 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 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 will return 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

Frequency_cap Attributes - Child Attributes of Delivery Attributes

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.

Override Attribute Definitions

Content Targeting Attributes - Child Attributes of Basic Attributes

The content targeting data should be grouped under the 'content_targeting' node.

Advanced Content Targeting Attributes - Child Attributes of Basic Attributes

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

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

Note: 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.

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

Note: 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.

Metadata Attributes - Child Attributes of Basic Attributes

The metadata data should be grouped under the 'metadatas' 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, please click here. Please 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.

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.

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

Upfront Association Attributes - Child Attributes of Basic Attributes

The upfront associate data should be grouped under the 'upfront_association' node.

Note: Upfront Association is an optional feature that must be turned on by your Program Manager.

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: 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.