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

439439

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.

978978

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

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.

  • Inactive
  • Active

Deal State Diagram for Buyers

Here are the states for a buyer for a deal synced without a status.

978978

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:

  • **INACTIVE**
  • **ACTIVE**
  • **PAUSE**
  • **COMPLETE**

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

🚧

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