Create a deal

POST

Creates the core deal objects with associated deal IDs

Update a deal

PATCH

Adds all the relevant deal configuration information

Retrieve a deal

GET

Retrieves deal configuration details

Activate a deal

PUT

Sets the deal status to activated

Deactivate a deal

PUT

Sets the deal status to deactivated

id

FW_ID

Integer

An integer number in FreeWheel

No

Yes

No

Not required when creating a new deal

deal_type

enum

• DEAL
• PROGRAMMATIC_GUARANTEED_DEAL
• FIRST_LOOK_DEAL
• FIRST_LOOK_DEFER_TO_DIRECT_SOLD_SPONSORSHIPS
• BIDDABLE_GUARANTE* ED_DEAL
• BACKFILL_DEAL

Deal types supported for a programmatic deal

Yes

Yes

No

Required when creating a new deal

external_deal_id

string

empty, or <= 255 characters

A globally unique identifier.

Yes

No

Yes

An automatically generated external deal ID is returned when a deal is created.

name

string

<= 255 characters

Yes

Yes

Yes

Required when creating a new deal

description

string

<= 4096 characters

No

Yes

Yes

Default is empty

salesperson

string

<= 255 characters

No

Yes

Yes

buyers

set

Set<FW_ID>

Buyers are invited on this deal to bid on an ad request

Yes

No

Yes

Size limit of 100 buyers per deal.

Required when pushing the deal setting

content_targeting

ContentTargeting

You can leverage the existing FreeWheel Inventory API:

• Video API v4.
• Site API v4

Inventory items targeted on the deal

Yes

No

Yes

ad_units

AdUnits

AdUnits

Ad units targeted on the deal

Yes

No

Yes

Size limit of 100 ad units per deal.

Check the Ad Unit API to see how to get ad unit.

Supported ad unit types:

• Standard
• Custom
• Variant

volume

volume

Volume

The volume of the deal

Yes

No

Yes

Required when pushing deal detail settings

pricing

pricing

Pricing

The price of the deal

Yes

Yes

Yes

Programmatic Guaranteed (PG): Must be fixed price

Others: Fixed or Floor price

schedule

schedule

Schedule

The Schedule (start and end dates) of the deal

Yes

No

Yes

Required when pushing deal detail settings

status

string

• ACTIVE
• INACTIVE (Default)
• ARCHIVE/li>
• PAUSE
• COMPLETED

No

No

Yes

Default is INACTIVE

max_ad_duration

integer

Ad duration in seconds, -1 means no limit

No

No

Yes

Default is -1

buyer_priority_override

integer

[-1, 0, 1, ..., 10]

Override the buyer priority for buyers behind this deal.

0 means do not override.

No

No

Yes

Default is 0.

Only for DEAL type

separate_bid

• bool
• true
• false

This feature is controlled under a specific network function (SEPARATE_BID_REQUEST) which limits the max allowed deals to be set with a separate bid.

The default maximum number is 25 live deals with separate bids enabled.

No

No

No

PG: always True.

Default is False.

audience_targeting

AudienceTargeting

AudienceTargeting

Audience items targeted on the deal

No

No

Yes

The maximum number of items for targeting is 4000.

platform_targeting

PlatformTargeting

PlatformTargeting

Platform items targeted on the deal

No

No

Yes

The maximum number of items for targeting is 4000.

geo_targeting

GeoTargeting

GeoTargeting

Geo items targeted on the deal

No

No

Yes

The maximum number of items for targeting is 4000.

daypart_targeting

DaypartTargeting

DaypartTargeting

Daypart items targeted on the deal

No

No

Yes

The maximum number of items for targeting is 4000.

7 * 24 by default

custom_targeting

CustomTargeting

CustomTargeting

Custom items targeted on the deal

No

No

Yes

The maximum number of items for targeting is 4000.

isp_targeting

set

Set<FW_ID>

ISP items targeted on the deal

No

No

Yes

The maximum number of items for targeting is 4000.

brand_restriction

restriction

Restriction

Restricted brands on the deal

No

No

Yes

Size limit of 1000 brand restrictions per deal !!!

Using global brand items

advertiser_restriction

restriction

Restriction

Restricted advertisers on the deal

No

No

Yes

Size limit of 1000 advertiser restrictions per deal.

Using global advertiser items

banned_industry

set

Set<FW_ID>

Restricted industries on the deal industry-ids list

No

No

Yes

You cannot use the API for listing industries. You need to export the data from MRM.

vpaid

bool

• True
• False

Indicated if VPAID is supported.

No

No

Yes

frequency_cap

FrequencyCaps

FrequencyCap

Frequency caps on the deal

No

No

Yes

Supports a maximum of 3 frequency cap items

creative_approval

CreativeApproval

CreativeApproval

Creative approval type and clearance method for the deal

No

No

Yes

override

override

For Guaranteed priority deal, the value is for above-paying ads and among paying ads.

For First Look deal, the value is for prioritization across First Look deals

No

No

Yes

PG & BG supports:

• above paying
• amongst paying

First Look supports prioritization across First Look deals.

DEAL supports override buyer priority which is represented by the buyer_priority_override field.

BF does not support.

items

Set

ad units

Ad units for the deal (e

No

id

FW_ID

integer

FW_ID of the ad unit

Yes

status

enum

ACTIVE or
INACTIVE

Status of ad unit assignment

Yes

id

FW_ID

integer

FW_ID of the buyer

Yes

buyer_platform

string

<= 255 characters

Buyer platform name of the buyer

Yes

trading_desk

string

<= 255 characters

Trading desk name of the buyer

Yes

external_seat_id

string

empty, or <= 255 characters

External seat id of the buyer

Yes

The default seat is empty.

control_pace

enum

• EVEN
• AS_FAST_AS_POSSIBLE

The deal's pacing

Yes

• DEAL and Backfill (BF) only support Fast As (AS_FAST_AS_POSSIBLE)
• First Look (FL) Programmatic Guaranteed (PG) and Biddable Guaranteed (BG) support Smooth As (EVEN) and Fast As (AS_FAST_AS_POSSIBLE)

control_period

enum

• DAY
• MONTH
• LIFECYCLE

The deal's impression goal period

Yes

• PG & BG only support per Life Cycle
• FL, DEAL & BF support per DAY, MONTH, and LIFECYCLE

excess_delivery_curve

enum

• spiky-ext-none
• spiky-ext-tiny
• spiky-ext-conservative
• spiky-ext-moderate
• spiky-ext-aggressive
• spiky-ext-unlimited

The deal's excess delivery setting

No

Only PG & BG support excess delivery

fixed_value

integer

0 ~ 2147483647

The deal's fixed impression goal

Yes

• PG & BG only support a fixed impression goal
• FL, DEAL & BF support no limit and fixed impression goal

no_limit

bool

bool

It represents a deal with no limit.

Yes

impression_goal

integer

0 ~ 2147483647

The deal's fixed impression goal

Yes

PG & BG only support a fixed impression goals.

FL, DEAL & BF support no limit and fixed impression goals.

excess_delivery_curve

enum

0%

5%

20%

50%

70%

UNLIMITED
NETWORK_DEFAULT

Deal's excess delivery setting

No

Only PG & BG support excess delivery

mode

string

For PG/BG:

• ABOVE_PAYING_ADS
• AMONGST_PAYING_ADS

For First Look, the mode is an empty string.

The override type

Yes

PG & BG support only.

For First Look deals, mode is meaningless.

value

integer

• The range of values for ' Amongst Paying Ads ' is 1 to 100;
• The range of value for 'Above Paying Ads' is 11 to 20;
• The range of value for 'First Look' is 21 -- 30, Default value is 25

The override value

Yes

start_time

string

A time string such as 2021-01-01T00:00

The start time of the deal

Yes

end_time

PG & BG: Required
Others: Optional

Time

A time string

The end time of the deal

• PG & BG: Required
• Others: Optional

time_zone

string

See MRM Time Zones

The time zone of the deal

Yes

model

enum

• FIRST_FLOOR
• SECOND_FLOOR
• FIXED

The pricing model of the deal

Yes

SECOND_FLOOR by default

price

double

0.01 ~ 1,000,000.00

The pricing value

Yes

currency_override

string

Use currency code, such as CAD or USD.

The currency to be used for the bidding.

No

This currency shares the global currency exchange rate with the network default currency.

type

enum

• NETWORK_DEFAULT
• NO_APPROVAL
• GLOBAL
• CLIENT

The approval type

Yes

NETWORK_DEFAULT by default

clearance_level

enum

• PERMISSIBLE
• RESTRICTED

The clearance type

Yes

PERMISSIBLE by default

items

Set<FrequencyCap>

Frequency caps

The frequency caps of a deal

No

value

integer

< 2147483647

The impression cap value

Yes

period

integer

Minutes for Time Scope

The cap period in minutes

Yes

type

enum

• TIME
• STREAM
• ASSET
• SITE_SECTION
• LIFETIME

The cap axis options

Yes

network_items

ContentTargetingNetworkItems

The API only supports MRM content. The default logical relationship between network_items, and standard_attributes, ron is OR.

standard_attributes and ron are valid for Marketplace clients only. Contact FreeWheel if you would like to enable Marketplace functionality, i.e., FW_MARKETPLACE_BUYER_PROFILE or FW_MARKETPLACE_SELLER_PROFILE, and ENABLE_MPP_INVENTORY_FOR_PROGRAMMATIC.

No

standard_attributes

ContentTargetingStandardAttributes

The API only supports MRM content. The default logical relationship between network_items, and standard_attributes, ron is OR.

standard_attributes and ron are valid for Marketplace clients only. Contact FreeWheel if you would like to enable Marketplace functionality, i.e., FW_MARKETPLACE_BUYER_PROFILE or FW_MARKETPLACE_SELLER_PROFILE, and ENABLE_MPP_INVENTORY_FOR_PROGRAMMATIC.

No

ron

Ron

The API only supports MRM content. The default logical relationship between network_items, and standard_attributes, ron is OR.

standard_attributes and ron are valid for Marketplace clients only. Contact FreeWheel if you would like to enable Marketplace functionality, i.e., FW_MARKETPLACE_BUYER_PROFILE or FW_MARKETPLACE_SELLER_PROFILE, and ENABLE_MPP_INVENTORY_FOR_PROGRAMMATIC.

No

include

TargetingSets

Yes

Targeting on raw Hylda Items is not supported in either the Programmatic Deal Open API or in the Marketplace user interface.

exclude

TargetingItems

No

include

StandardAttributeItems

Yes

exclude

StandardAttributeItems

No

include

RonItems

RonItems

Included RON items

Yes

rovn

boolean

• True
• False

Indicates whether ROVN is enabled or not

Yes

Default is False.

rosn

boolean

• True
• False

Indicates whether ROSN is enabled or not

Yes

Default is False.

romn

boolean

• True
• False

Indicates whether ROMN is enabled or not

Yes

Default is False.

include

GeoSetAtrribute

GeoSetAtrribute

Geographic attributes are included.

No

exclude

GeoSetAtrribute

GeoSetAtrribute

Geographic attributes are excluded.

No

country

Set

Set<FW_ID>
Country List

A set of FW ID of countries

No

state

Set

Set<FW_ID>; States, Provinces, and Regions List

A set of FW ID of states

No

dma

Set

Set<FW_ID>; US DMA List

A set of FW ID of DMAs

No

city

Set

Set<FW_ID>; Cities List

A set of FW ID of cities

No

postal_code

Set

Set<FW_ID>; Postal Code List

A set of FW ID of postal codes

No

postal_code_package

Set

Set<FW_ID>; Postal Code List

A set of FW ID of postal code packages

No

region

Set

Set<FW_ID>; States, Provinces, and Regions List

A set of FW ID of regions

No

include

Set

Set<FW_ID>

A set of FW ID of ISPs

No

set

set

Set

If there are multiple sets, then the relationship within a set can only be "ANY". Across sets, the relationship is "AND".

No

Need to confirm if the validation already exists or Targeting Service handles it

relation_between_sets

Set

Set

If there is more than one set, match can only be set to OR. If there is only one set with multiple key values, the match can be OR or AND.

No

Required if there is only one set.

Need to confirm if the validation already exists or Targeting Service handles it

key_value

Set

The string value format is k=v

A key-value set

No

The string value format =

relation_in_sets

RelationType

RelationType

Relation in sets

Yes

include

TargetingSets

The included audience items

No

exclude

TargetingItems

The excluded audience items

No

video

Set<FW_ID>

Set of FW_ID

FW ID set of videos

No

Omit the node by default

video_group

Set<FW_ID>

Set of FW_ID

FW ID set of video groups

No

Omit the node by default

series

Set<FW_ID>

Set of FW_ID

FW ID set of video series

No

Omit the node by default

site

Set<FW_ID>

Set of FW_ID

FW ID set of site

No

Omit the node by default

site_section

Set<FW_ID>

Set of FW_ID

FW ID set of site section

No

Omit the node by default

site_group

Set<FW_ID>

Set of FW_ID

FW ID set of site group

No

Omit the node by default

site_section_group

Set<FW_ID>

Set of FW_ID

FW ID set of channel

No

Omit the node by default

audience_item

Set<FW_ID>

Set of FW_ID

FW ID set of audience items

No

Omit the node by default

relation_in_set

RelationType

RelationType

The relations in a set

No

Omit the node by default

relation

enum

• AND
• OR

A relation type

Yes

relation_between_sets

Set

The relation between sets

Yes

sets

Set

The set of targeting items

Yes

remaining_items

TargetingItems

The set of targeting item

No

time_zone

string

A time zone name

Yes

FreeWheel provides a list of time zones

part

Set

A set of daypart targeting part (tick)

Yes

Maximum size = 12

start_time

enum

'12 MIDNIGHT', '01:00AM', '02:00AM', '03:00AM', '04:00AM', '05:00AM', '06:00AM', '07:00AM', '08:00AM', '09:00AM', '10:00AM', '11:00AM', '12 NOON', '01:00PM', '02:00PM', '03:00PM', '04:00PM', '05:00PM', '06:00PM', '07:00PM', '08:00PM', '09:00PM', '10:00PM', '11:00PM'

The start time of a day

Yes

end_time

enum

'01:00AM', ' 02:00AM ',
'03:00AM', ' 04:00AM', '05:00AM', '06:00AM', '07:00AM', '08:00AM',
'09:00AM', '10:00AM', '11:00AM', '12 NOON', '01:00PM', ' 02:00PM ',
'03:00PM', '04:00PM', '05:00PM', '06:00PM',
'07:00PM', '08:00PM', '09:00PM', '10:00PM', '11:00PM', ''11 :59PM'

The end time of a day

Yes

start_day

enum

• SUNDAY
• MONDAY
• TUESDAY
• WEDNESDAY
• THURSDAY
• FRIDAY
• SATURDAY

The start day of a week repeated weekly

Yes, when repeating daily

end_day

enum

• SUNDAY
• MONDAY
• TUESDAY
• WEDNESDAY
• THURSDAY
• FRIDAY
• SATURDAY

The end day of week repeated weekly

Yes, when repeating daily

days

Set

• SUNDAY
• MONDAY
• TUESDAY
• WEDNESDAY
• THURSDAY
• FRIDAY
• SATURDAY

The repeated day of the week

Yes, when repeating daily

repeats

enum

• DAILY
• WEEKLY

The repeated type

Yes

device

Set <FW_ID>

Valid Platform IDs

No

os

Set <FW_ID>

Valid Platform IDs

No

browser

Set <FW_ID>

Valid Platform IDs

No

package

Set <FW_ID>

Obtained from MRM

No

standard_attributes

Set of Standard Attributes inclusion and exclusion

include

Set of Standard Attribute Items

Set of Standard Attributes. Each Standard Attribute must contain a type and at least one ID.

No

The relationship between each Standard Attribute type is AND. The relationship between each Standard Attribute item under the same type is OR.

exclude

Set of Standard Attribute Items

Set of Standard Attributes. Each Standard Attribute must contain a type and at least one ID.

No

The relationship between each Standard Attribute type is AND. The relationship between each Standard Attribute items under the same type is OR.

standard_attribute

Set

Set of StandardAttributes

Each Standard Attribute must contain a type and at least one ID

Yes

type

enum

• DEVICE
• OS
• ENVIRONMENT
• GENRE
• PROGRAMMER
• FORM
• LANGUAGE
• RATING
• ENDPOINT_OWNER
• ENDPOINT

Marketplace pre-defined standard attributes types that can be targeted

Yes

Platform SA:

• DEVICE
• OS
• ENVIRONMENT
• ENDPOINT_OWNER
• ENDPOINT

Content SA:

• GENRE
• PROGRAMMER
• FORM
• LANGUAGE
• RATING

id

set

Set<FW_ID>

ID of corresponding Standard attributes value that can be targeted

Yes

Use the Standard Attribute API to get the list of Standard Attribute IDs to target. If you want to target multiple items in the same type, add more nodes in parallel. At least one id must be included.

mode

enum

• ALLOW
• BLOCK

Specifies the restriction mode

Yes

id

Set

Set<FW_ID>

A set of FW ID of restricted items (brand, advertiser, or industry)

Yes