Overview
This document specifies details you need to design your system for interacting with AutoScheduler’s order upload process via the FreeWheel Open API, including the required format for the uploaded file.
For Authentication procedures, see Getting Started with Authentication.
Environments
| Environment | URI |
|---|---|
| Staging | https://api.stg.freewheel.tv/services/v4/linear_orders |
| Production | https://api.freewheel.tv/services/v4/linear_orders |
Basic Attributes Field
Each record represents a unit-based linear order line. You can post multiple lines through the same POST call.
| Field | Required? | Type | Description |
|---|---|---|---|
| Name | optional | string | If not passed, this field is auto-generated and stored in FreeWheel’s system. |
| external_id | required | string | Order.line.id in your system. Each line has a unique external_id. |
| parent_external_id | required | string | Order.id in your system |
| advertiser_external_id | required | int | Advertiser ID associated with order in your system |
| advertiser_name | optional | string | Name of the advertiser |
| start_date | required | date | Format: %yyyy-%mm-%dd |
| end_date | required | date | Format: %yyyy-%mm-%dd |
| duration | required | int | In seconds (15,30,60) |
| budget.type | required | string | Only UNIT is allowed. |
| budget.total_unit | required | int | Number of units requested |
| price | required | float | Price of each unit in dollars |
| priority_code | required | int | Priority of this line in your system. FreeWheel recognizes and respects the line priority only through the code value. If there are multiple priority code systems, you need to consolidate them before sending to FreeWheel. |
| targeting.content.channel.include[].network_code | required | array of strings | Network code of the channel. This must match with the CorpNetworkCode column in the capacity file that you would upload for AutoScheduler usage. |
| targeting.geo.zone.include[].syscode | required | array of strings | Node is required, but it can be empty. If the node is empty, by default AutoScheduler considers all eligible syscodes. |
| targeting.dayparts.days_of_week | required | array of int | Node is required but it can be empty. If the node is empty, by default AutoScheduler considers all days, e.g., Mon – 1, Tues – 2, …, Sun - 7 |
| targeting.dayparts.parts | required | array of from and to string | Example: HH:MM from: “04:00” to: “06:00” |
Amazon S3 Integration
To integrate with Amazon Simple Storage Service (S3), you need to upload files to an Amazon Web Services (AWS) S3 bucket managed by FreeWheel, which requires an AWS access key.
There are two ways to handle the AWS key
1. Provide Your Amazon Resource Name (ARN) to FreeWheel (Recommended)
- You provide FreeWheel with the ARN from your Amazon Web Services (AWS) account.
- FreeWheel creates an AWS role that gives your AWS account permissions to upload and list files in your dedicated folder.
2. FreeWheel Provides an AWS Key
FreeWheel gives you an AWS access key that grants permissions to upload and list files in your dedicated folder.
Note
In the second approach, the AWS account is owned by FreeWheel, and is subject to
FreeWheel's key rotation schedule. This scenario requires more communication between
you and FreeWheel than the first approach.
File Specifications
- Must be a zipped, comma-delimited .csv file with a file size of no more than 500MB.
- Each line in the file must represent one order line.
-
File name must follow this convention:
- linear_orders_{date of orders}_{timestamp}.csv
- String type fields must be enclosed within quotation marks.
- If the order line is for regional syscode, then syscode_inclusions must have a comma-separated list of local syscodes for that regional syscode. This means the number of units specified in that line can air in any of those syscodes.
CSV File Data Fields
Note
contractid+tb _system_id+order_line must be unique within the CSV file. These three fields compose the external_id
| Field | Data Type | Format |
|---|---|---|
| contractid | Integer | |
| tb_system_id | Integer | |
| order_start_date | String | YYYYMMDD: 20060102 |
| order_end_date | String | YYYYMMDD: 20060102 |
| advertiser_name | String | |
| advertiser_code | String | |
| order_line | Integer | |
| spot_length | Integer | |
| prioritycode | Integer | |
| broadcast_week | String | 20201 |
| bookingdesc | String | 16:00-20:00 must split by "-" |
| orbits | Char | N: false Y: true |
| syscode | Array of Integer | |
| gross_dollars | Array of Float32 | |
| buget_units | Array of Integer | |
| duration | Array of Integer | |
| networkname | Array of String | |
| networkcode | Array of String | |
| marketname | Array of String |