For details on API authentication, see Authentication for FreeWheel Demand APIs.
Overview
This document is intended for demand-side parties interested in automating the process by which Deal ID terms are synchronized with FreeWheel. The document guides you through integrating with FreeWheel’s Deal Sync API and its intended use.The FreeWheel Deal Sync AP v1.1.0 is designed to simplify the trafficking process of programmatic deals between Demand Side Platforms (DSPs) and FreeWheel. Most TV programmatic transactions are Deal-ID based, which are not fully supported by automated processes today. Many manual processes, such as emails and/or phone calls, are required today. The FreeWheel Deal Sync API automates these processes by automatically syncing Deal ID based transaction settings between platforms to eliminate manual work and minimize human errors.
Important
The Deal Sync API is only for Deal ID based transactions executed through OpenRTB.
Workflows
The Deal Sync API was designed with the following workflows in mind:
- DSP Workflow
- Buyer Workflow
- Approval Workflow
- Rejection and Update Workflow
This section also includes a:
- Buyer Status Table
DSP Workflow Sequence Diagram
The DSP workflow returns all active Deals targeted to the requesting DSP. This workflow is intended to support internal DSP user (DSP employee) use cases. DSP clients (buyers) must utilize the Buyer workflow documented on the following page.
DSP Workflow Description
Publisher
- Ad Ops creates deal in FreeWheel
- Assigns buyers to the deal (DSP/Seat ID)
- Assigns other transaction settings.
FreeWheel
- Responds that deal has been created .
DSP
- Calls Deal Sync API
FreeWheel
- Deal Sync API returns all active deals in FreeWheel for the requesting DSP
Buyer Workflow Sequence Diagram
The Buyer Workflow returns all active Deals targeted to the requesting DSP Seat. This workflow is intended to automate the Deal trafficking process between buyer and seller.
Buyer 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 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.
Approval Workflow Sequence Diagram
Approval Workflow Description
Seller
- Creates a deal.
DSP
- Runs and an API GET request to retrieve the deals.
MRM Programmatic Module
- Sends the list of deals.
Buyer
- Views and approves the deal.
DSP
- Sends an API PUT request to updates the MRM Programmatic Module.
MRM Programmatic Module
- Returns the approvalstaus object to the DSP.
Seller
- Views the approved deal.
Rejection and Update Workflow Sequence Diagram
Rejection and Update Workflow Description
Seller
- Creates a deal.
DSP
- Runs and an API GET request to retrieve the deals.
MRM Programmatic Module
- Sends the list of deals.
Buyer
- Views and rejects the deal.
DSP
- Sends an API PUT request to updates the MRM Programmatic Module.
MRM Programmatic Module
- Returns the approvalstaus object to the DSP.
Seller
- Views the rejected deal and updates it in the MRM Programmatic Module.
DSP
- Runs and an API GET request to retrieve the deals.
MRM Programmatic Module
- Sends the list of deals.
Buyer
- Views and approves the updated deal.
DSP
- Sends an API PUT request to updates the MRM Programmatic Module.
MRM Programmatic Module
- Returns the approvalstaus object to the DSP.
Seller
- Views the approved deal. # Objects and Parameters
Buyer
- Modifies status in DSP.
DSP
- Sends PATCH /deals to update MRM Programmatic Module.
Buyer Status Table
Buyer Status | Definition |
|---|---|
{empty} | The deal status is not supported because it is a FreeWheel SSP (SFX) deal or a non Programmatic deal. During the initial deal-sync workflow, non programmatic deals that are not supported have an empty status. For any newly created Programmatic or Non-Programmatic deals, the DSP Status is described as Not Applicable in the UI and is empty in the database. The status Not Applicable only changes when a DSP sends back an associated status. |
INACTIVE | The deal is not ready to be served yet. This is the status that initially gets synced over to a buyer. |
ACTIVE | The deal is ready for bid requests |
PAUSE | The deal is paused by the buyer |
COMPLETE | The deal has been completed as confirmed by the flight date "END" |
Status Diagram
Deals Object
The approvals functionality included in the parameters below is not supported yet.
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 will be 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 1 = Managed. FreeWheel manages creative approval on behalf of the seller 2 = Client. The seller manages creative approval themselves | integer | Yes |
approvalstatus | Object containing the approval status of deals that have either been approved or rejected | object array | Optional |
buyerstatus | Object that contains information that can only be modified by the buyer. This can be updated via PATCH. 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. See the table below. | Object |
Buyer Status Object
Note: This buyer status functionality will be not available until 6.48 release scheduled for March 2022.
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
This seller status functionality will be not available until 6.49 release scheduled for May 2022.
Property | Description | Type | Required? |
|---|---|---|---|
status | A field within the sellerstatus object, it provides the status of the deal on the seller side. This can only be modified by a seller. | enum Valid values:
| Yes |
comment | A field contained within the sellerstatus object, this allows a seller to input comments explaining why the sellerstatus has changed. | string | No |
The approvalstatus Object
approvalstatus ObjectThe approvalstatus object only appears if a DSP is integrated with our PUT accounts/[id]/deals/[dealid]?approve or accounts/[id]/deals/[dealid]?reject and has submitted their deal approval/rejection.
Property | Description | Type | Returned in GET? |
|---|---|---|---|
status | The approval status of the deal ID | enum
| Yes |
seatid | The buyer seatid to which the status relates. | string | Yes |
rejectreason | The reason the deal was rejected, provided by the buyer | string Maximum characters: 500 | Yes |
updatedat | The timestamp of the last update of the approval status | datetime (ISO8601) | 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