For details on API authentication, see Authentication for FreeWheel Demand APIs.
Overview
This document is for demand-side parties interested in automating the process by which Deal ID terms are synchronized with FreeWheel.
The FreeWheel Deal Sync AP v1.1.0 is designed to simplify the trafficking of programmatic deals between FreeWheel and Demand-Side Platforms (DSPs). Most TV programmatic deals are deal-ID based transactions whose processes have traditionally been handled through emails or phone calls. The FreeWheel Deal Sync API automates these processes by syncing deal-ID-based transaction settings between platforms to eliminate manual work and minimize human error.
Important
The Deal Sync API is only for deal-ID-based transactions executed through OpenRTB.
Deal Sync API Workflow
Deal Sync API Workflow Description
Publisher
- Ad Ops creates a deal in MRM.
- Assigns buyers to the deal (DSP/Seat ID).
- Assigns other transaction settings.
FreeWheel
- Responds that the deal has been created.
DSP
- Calls Deal Sync API, passing Seat ID in the request.
- Deal Sync API returns all active deals in FreeWheel SSP for the requesting DSP Seat.
FreeWheel
- Returns all active deals targeted to a particular DSP.
An active deal targeted to a particular DSP is a transaction with a Deal ID.
Deal State Diagrams
Deal State Diagram for Sellers
Here are the states for a deal after it is created in MRM.
Deal States for Sellers
The following, except Pause, can only be updated by sellers.
| State | Description | Can be changed to: |
|---|---|---|
| Active | FreeWheel sends bid requests for this particular deal. |
|
| Inactive | A status of Inactive prevents a bid request from being sent for that deal. | Any other state |
| Pause | FreeWheel automatically changes the deal’s status to Pause if the deal has two weeks of inactivity. Note: Sellers cannot change a deal to this state. | Inactive |
| Complete | The deal is complete and the flight date has ended. |
|
Deal State Diagram for Buyers
Here are the states for a buyer for a deal synced without a status.
The following can only be updated by buyers.
| State | Description |
|---|---|
| Active | The deal is ready for bid requests. |
| Inactive | The Inactive status identifies deals that have been synced over to the DSP but are not ready to serve initially. When a deal gets synced over, its status is empty rather than Inactive. FreeWheel assumes No Status refers to the deal's not being synced over. So the status needs to be changed from N/A- Empty to Inactive. Buyers should only act on the Buyer status changes to communicate the deal's readiness. |
| Pause | The same as Inactive. However, a separate status is provided so that a seller can know the status. Pause means the deal was acted upon by the buyer during the life of the campaign. However, you can send a deal with an Inactive status. |
| Complete | The deal is complete and the flight date has ended. |
Deals Object
| Property | Description | Type | Returned in GET? |
|---|---|---|---|
| dealid | The deal ID | string | Yes |
| name | The deal name | string | Yes |
| volume | Impression cap for the deal. If null, the deal has no impression cap. | int | Optional |
| flr | The applied floor price. (If the auction type is 3, this is the fixed price). | decimal | Optional |
| flrcur | Deal currency using ISO-4217 alpha codes | string | Optional |
| at | Auction Type. 1. First price 2. Second price 3. Fixed price | integer | Yes |
| startdate | Start date/time of this deal in UTC, ISO-8601 | datetime (ISO8601) | Yes |
| enddate | End date/time of this deal in UTC, ISO-8601 | datetime (ISO8601) | Optional |
| updatedat | Indicates the time in which any modifications to this deal are made. | datetime (ISO8601) | Yes |
| createdat | Indicates the time in which the deal was created. | datetime (ISO8601) | Yes |
| guaranteed | Indicates whether or not this is a PG deal. | boolean (1 or 0) | Yes |
| seats | The list of seats targeted to the deal | array of strings | Optional |
| sellerid | Unique ID representing the end seller of the Deal ID See also: sellers.json documentation | array of strings | Yes |
| clearancelevel | Indicates the seller creative clearance level setting for a particular deal ID. 1 = Restrictive. The creative must be approved to go live. 2 = Permissive. Creative approval is not required to go live. | integer | Yes |
| approvaltype | Indicates the seller approval type setting for a particular deal ID 0 = No approval is needed. 1 = Managed. FreeWheel manages creative approval on behalf of sellers. 2 = Client. Sellers manage creative approval themselves | integer | Yes |
| buyerstatus | Object that contains information that can only be modified by the buyer See the table below. | object | |
| sellerstatus | Contains the status of the deal on the seller side. This can only be modified by a seller. This should refer to the existing statuses in the Programmatic Module. | enum |
Buyer Status Object
| Property | Description | Type | Required? |
|---|---|---|---|
| status | A field within the buyerstatus object, it provides the status of the deal on the buy side. This can only be modified by a buyer. | enum Valid values:
| Yes |
| comment | A field within the buyerstatus object, it allows a seller to input their reasons for changing the buyer status. This can only be modified by a buyer. | string | No |
Seller Status Object
| Property | Description | Type | Required |
|---|---|---|---|
| status | A field within the sellerstatus object, it provides the status of the deal on the buy side. This can only be modified by a seller. | enum Valid values:
| Yes |
Important
This schema may change as future enhancements are made to the current API version. FreeWheel highly recommends performing loose schema validations while integrating to the API