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
Refer to the following documentation for more information about FreeWheel products and APIs:
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]&...
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.
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 No No No
Name Type(s) Mandatory Details role_id Integer Yes Pre-defined system-level role IDs role_name String No Role name. Only returned in GET action. PUT/POST ignore it if passed.
Name Type(s) Details Mandatory assigned_user Set Array of assigned user(s) Yes
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.
Name Type(s) Details Mandatory Notes budget_model Valid values: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.
Name Type(s) Details Mandatory Notes contact_type String Type of contact Yes name String Name of contact Yes phone String Phone number of the contact Yes email String Email of the contact Yes primary Boolean Yes, if the contact is primary No Only one contact can be set as the primary contact. If this field is not set, we will set the default value: FALSE
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.
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: 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
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 workflow_step Set The workflow step workflow_step_owners Set Workflow step owners count_in_revenue_forecast Boolean If the insertion order counts in revenue forecasting ecpm Set cost Set The gross and net cost of the insertion order
The following attributes are only available for Networks with Sales Proposal enabled:
Name Type(s) Details rfp_budget Float RFP budget rate_card_id FW_ID Rate card ID total_billable_event_goal Integer total_p2plus_impressions Integer primary_variant_id FW_ID Primary variant ID
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
Name Type(s) Details Mandatory Notes workflow_step_id FW_ID The id of this workflow step Yes Only available for Networks with Sales Proposal enabled workflow_step_name String The name of this workflow step Yes workflow_step_type Workflow step type Yes If Sales Proposal is enabled, workflow_step_type will return in response body.
Name Type(s) Details Mandatory user_id FW_ID The id of the user No user_group_id FW_ID The id of the user group No role_id FW_ID The id of the role No
Name Type(s) Details Mandatory gross_ecpm Float (2 decimal places) The gross eCPM Yes net_ecpm Float (2 decimal places) The net eCPM Yes
Name Type(s) Details Mandatory Notes gross_cost Float (2 decimal places) The gross cost Yes When enabling sales proposals, cost value will be retrieve from primary variant's placements. net_cost Float (2 decimal places) The net cost Yes When enabling sales proposals, cost value will be retrieve from primary variant's placements.
