For details on API authentication, see Authentication for FreeWheel Demand APIs.
Overview
This document is for demand-side parties interested in automating the process of retrieving, filtering, and updating buyer status on deals processed by FreeWheel. The FreeWheel Deal Sync API is designed to simplify trafficking of programmatic guaranteed (PG) deals and select private marketplace (PMP) deals for demand-side platforms.
Most TV programmatic deals are deal-ID based transactions, whose processes have traditionally been handled through offline processes. 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.
In order to curate lists of deal IDs, the FreeWheel Deal Sync API offers the ability to pull and filter all deals associated with a seat. Demand-side platforms can filter programmatic deals by parameters like start date, as well as fetch PMP deals marked for pre-approval. Once retrieved, deal IDs can be associated with creatives in the Demand Creative Management API V1.
Note
PMP pre-approval deals will only appear from publishers that enable the associated network function.
Deal Sync API Workflows
Retrieve All Deals
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
- Requests a list of deals, passing the seat ID in the request, as well as any desired parameters.
FreeWheel
- Returns all deals targeted to a particular DSP that match the DSP's request parameters.
Note
An active deal targeted to a particular DSP is a transaction with a Deal ID.
Update Buyer Status
DSP
- Requests list of all deals to review deals'
buyerstatus.
FreeWheel
- Retrieves a list of all deals in the client network. Each deal contains a
buyerstatusobject with a status and comment from the buyer.
DSP
- Sends a PATCH request with the deal's ID. Includes a change to the status or comment.
FreeWheel
- Buyer status successfully updated.
Deal State Diagrams
Deal States for Sellers
Here are the states for a deal after it is created in MRM.
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 |
| Archive | Freewheel specific status that represents a deal that is Inactive that can no longer be activated in the future and is no longer usable **Deal cannot be updated once set to this status | Cannot be changed back to any other status |
| Complete | The deal is complete and the flight date has ended. |
|
Deal States 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 | |
| preingestpermissions | Indicates which type of pre-approval permission corresponds to a deal. Pre-ingestion is a back-end term for pre-approval. 1 = Required. Represents PG deals. 2 = Allowed. Represents PMP deals that the publisher allows for pre-approval. 3 = Not Allowed. Represents all other deals that are not PG or have not been enabled for a buyer to pre-approve their creatives. 4 = Not Available. Represents all other deals that are not part of the existing MRM prog mod workflow. | integer | Yes |
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 buyer 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 sell 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.