Deal Sync API

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

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

FreeWheel

  1. Responds that deal has been created .

DSP

  1. Calls Deal Sync API

FreeWheel

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

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

FreeWheel

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

Approval Workflow Sequence Diagram

Approval Workflow Description

Seller

  1. Creates a deal.

DSP

  1. Runs and an API GET request to retrieve the deals.

MRM Programmatic Module

  1. Sends the list of deals.

Buyer

  1. Views and approves the deal.

DSP

  1. Sends an API PUT request to updates the MRM Programmatic Module.

MRM Programmatic Module

  1. Returns the approvalstaus object to the DSP.

Seller

  1. Views the approved deal.

Rejection and Update Workflow Sequence Diagram

Rejection and Update Workflow Description

Seller

  1. Creates a deal.

DSP

  1. Runs and an API GET request to retrieve the deals.

MRM Programmatic Module

  1. Sends the list of deals.

Buyer

  1. Views and rejects the deal.

DSP

  1. Sends an API PUT request to updates the MRM Programmatic Module.

MRM Programmatic Module

  1. Returns the approvalstaus object to the DSP.

Seller

  1. Views the rejected deal and updates it in the MRM Programmatic Module.

DSP

  1. Runs and an API GET request to retrieve the deals.

MRM Programmatic Module

  1. Sends the list of deals.

Buyer

  1. Views and approves the updated deal.

DSP

  1. Sends an API PUT request to updates the MRM Programmatic Module.

MRM Programmatic Module

  1. Returns the approvalstaus object to the DSP.

Seller

  1. Views the approved deal. # Objects and Parameters

Buyer

  1. Modifies status in DSP.

DSP

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

  • N/A
  • 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

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:

  • ACTIVE
  • INACTIVE
  • ARCHIVE
  • PAUSE

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

The 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

  • PENDING
  • APPROVED
  • REJECTED
  • SELLER_UPDATED

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