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

  1. Ad Ops creates a deal in MRM.
  • Assigns buyers to the deal (DSP/Seat ID).
  • Assigns other transaction settings.

FreeWheel

  1. Responds that the deal has been created.

DSP

  1. 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

  1. 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.

StateDescriptionCan be changed to:
ActiveFreeWheel sends bid requests for this particular deal.
  • Inactive
InactiveA status of Inactive prevents a bid request from being sent for that deal.Any other state
PauseFreeWheel 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
ArchiveFreewheel 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
CompleteThe deal is complete and the flight date has ended.
  • Inactive
  • Active

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.

StateDescription
ActiveThe deal is ready for bid requests.
InactiveThe 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.
PauseThe 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.
CompleteThe deal is complete and the flight date has ended.

Deals Object

PropertyDescriptionTypeReturned in GET?
dealidThe deal IDstringYes
nameThe deal namestringYes
volumeImpression cap for the deal. If null, the deal has no impression cap.intOptional
flrThe applied floor price. (If the auction type is 3, this is the fixed price).decimalOptional
flrcurDeal currency using ISO-4217 alpha codesstringOptional
atAuction Type.

1. First price
2. Second price
3. Fixed price
integerYes
startdateStart date/time of this deal in UTC, ISO-8601datetime (ISO8601)Yes
enddateEnd date/time of this deal in UTC, ISO-8601datetime (ISO8601)Optional
updatedatIndicates the time in which any modifications to this deal are made.datetime (ISO8601)Yes
createdatIndicates the time in which the deal was created.datetime (ISO8601)Yes
guaranteedIndicates whether or not this is a PG deal.boolean (1 or 0)Yes
seatsThe list of seats targeted to the dealarray of stringsOptional
selleridUnique ID representing the end seller of the Deal ID

See also: sellers.json documentation
array of stringsYes
clearancelevelIndicates 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.
integerYes
approvaltypeIndicates 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
integerYes
buyerstatusObject that contains information that can only be modified by the buyer

See the table below.
object
sellerstatusContains 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

PropertyDescriptionTypeRequired?
statusA 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:

  • INACTIVE
  • ACTIVE
  • PAUSE
  • COMPLETE
Yes
commentA 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.
stringNo

Seller Status Object

PropertyDescriptionTypeRequired
statusA 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:

  • INACTIVE
  • ACTIVE
  • PAUSE
  • COMPLETE
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