Introduction

Insertion Orders (IOs) act as organizational groups of Placements. The Actions and Settings applicable to IOs are managerial tasks and configurations that apply to all placements within an IO.

You can use the Insertion Order API V3 to:


View (List) insertion orders	Get specific widget information
Create insertion orders	List placements for an insertion order
Update insertion orders	List variants of an insertion order
Create a proposed insertion order	Transfer budget to an insertion order
Update a proposed insertion order	Book an insertion order
Show information about an insertion order	Unbook an insertion order
Delete an insertion order	Change proposal status of an insertion order

Resources

URI(s)

The Insertion Order API v3 identifies two Uniform Resource Identifiers (URIs), a List and an Instance as identified in the following table:

Type of URI	URI
Production	`https://api.freewheel.tv/v3/insertion_orders/[FW_ID].xml?[parameter1]=[query1]&...`
Staging	`https://api.stg.freewheel.tv/v3/insertion_orders/[FW_ID].xml?[parameter1]=[query1]&...`

Insertion Order API Attributes

Attributes represent and describe data associated with an object, in this case the Agency 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 Insertion Order API Attributes in conjunction with Insertion Order API methods to accomplish your ad tech objectives.

Create/Update Attributes

Parameter	Description	Data Type(s)	Creatable?	Updateable?	Mandatory	Comments
insertion_order_id	The identification number of the Insertion Order.	Integer	Yes	Yes	No	You can search, update, and delete by by the insertion_order_id.
name	Insertion Order name	String	Yes	Yes	Yes
description		String	Yes	Yes	No
client_po	Client purchase order	String	Yes	Yes	No
external_id	The external ID of the insertion order	String	Yes	Yes	No
primary_sales_person	Primary sales person name	String	Yes	Yes	No	On create only
primary_trafficker	Primary trafficker name	String	Yes	No	No	On create only
currency	The 3 letter currency codes	String	Yes	No	No	Valid when a network supports multiple currencies.
budget	The budget of the Insertion Order	Set	Yes	Yes	No
delivery	The delivery info of the insertion order	Set	Yes	Yes	No
stage	The stage of the insertion order	BOOKED NOT_BOOKED PROPOSAL	No	No	No

Assignments Attributes - Child Attributes of Create/Update Attributes

Name	Type(s)	Details	Mandatory
assigned_user	Set	Array of assigned user(s)	Yes

Assigned User Attributes - Child Attributes of Assignments Attributes

Name	Type(s)*	Mandatory	Details
user_id	Integer	Yes	Valid user ID
user_full_name	String	No	User full name. Only return in GET action. PUT/POST ignore it if passed.

Budget Attributes - Child Attributes of Create/Update Attributes

Name	Type(s)	Details	Mandatory	Notes
budget_model	Valid values: <ul CURRENCY_TARGET IMPRESSION_TARGET EVERGREEN	The budget model of the insertion order	Yes	EVERGREEN' is GET only
currency	Float	The currency goal of the insertion order	Yes	Valid and required only when budget_model == 'CURRENCY_TARGET'.
impression	Integer	The impression goal of the insertion order	Yes	Valid and required only when budget_model == 'IMPRESSION_TARGET'.
over_delivery_value	Float	The over delivery amount percentage	No	Valid only when budget_model == 'CURRENCY_TARGET' or 'IMPRESSION_TARGET'. If it is not set, the network default value is used.

Delivery Attribute - Child Attributes of Create/Update Attributes

The attribute below is not included in basic GET requests.

Function/Node	Description	Data Type(s)*	Creatable?*	Updateable?	Comments
frequency_cap	Set of frequency caps, for each frequency cap	Frequency Cap Attributes	Yes	Yes	Only 3 frequency caps are supported at most.

Frequency Cap Attributes - Child of Delivery Attribute

The attribute below can be included in basic GET requests.

Function/Node	Description	Data Type(s)	Creatable?	Updateable?
value	The cap value	Integer	Yes	Yes
type	The cap type valid values: IMPRESSION PACKAGE	Enum	Yes	Yes
period	The cap period valid enum values: TEN_MIN HOUR DAY WEEK 30DAYS STREAM ASSET SITE_SECTION CAMPAIGN	Enum or Integer: Specified in minutes	Yes	Yes

Body Attributes

Name	Type(s)	Details
id	FW_ID	ID of the insertion order
campaign_id	FW_ID	ID of the campaign that this insertion order belongs to
name	String	Insertion Order name
description	String	Both
client_po	String	Client purchase order
brand_id	FW_ID	The Brand ID of the advertiser
currency	String	The 3 letter currency codes
schedule	Set	A set of IO start time, end time, and timezone
stage	'BOOKED', 'NOT_BOOKED', 'PROPOSAL'	The stage of the insertion order
external_id	String	The external ID of the insertion order
primary_sales_person	String	Primary Sales Person name
primary_trafficker	String	Primary Trafficker name
budget	Set	The budget of the insertion order

Schedule Attributes - Child Attributes of Body Attributes

Name	Type(s)**	Details	Mandatory	Notes
start_time	Time	The start time of the placement\|	Yes	Uses ISO-8061 time format
end_time	Time	The end time of the placement	No	Uses ISO-8061 time format. If a Placement is ongoing, end_time is optional.
time_zone	String	The time zone of the placement\|	Yes