Legacy Programmatic Deal Open API V4

🚧

Please go to Programmatic Deal Open API V4 for the latest version of our API Reference.

Overview

This section outlines the technical specifications for FreeWheel's Deal Open API.

For details on API authentication, see Getting Started with Authentication.

The Deal Open API features these core endpoints.

FunctionMethod TypeDescription
Create a dealPOSTCreates the core deal objects with associated deal IDs
Update a dealPATCHAdds all the relevant deal configuration information
Retrieve a dealGETRetrieves deal configuration details
Retrieve List of AdvertisersGETRetrieves list of Advertisers, which can be sorted by days since last updated.
Retrieve a list of BrandsGETRetrieves list of Brands, which can be sorted by days since last updated.
Activate a dealPUTSets the deal status to activated
Deactivate a dealPUTSets the deal status to deactivated

In addition, you can use the Buyer list method to collect FreeWheel information necessary to populate deal object attributes.

Limitations

  1. The Programmatic Deal Open API does not support the following deal attributes:
  • Support ROVN/ROSN Exclusion
  • Metrics
  • IMRTargeting
  • Bid request restriction package
  • Primary Trafficker
  • Billing Override
  • Supply source targeting
  • Relationship targeting
  • Support Channel/Series/Daypart/StreamType SA targeting
  • FloorPricePolicy
  • Price support inheriting from the price of listing
  • Inbound MRM Rule transparency

Deal Push Workflow

Deal Object

The table below describes the attributes currently supported for the Deal Object..

NameTypeValueDescriptionRequired for activation??Deal Creation API?Deal Update API?Notes
idFW_IDIntegerAn integer number in FreeWheelNoYesNoNot required when creating a new deal
deal_typeenum
  • DEAL
  • PROGRAMMATIC_GUARANTEED_DEAL
  • FIRST_LOOK_DEAL
  • FIRST_LOOK_DEFER_TO_DIRECT_SOLD_SPONSORSHIPS
  • BIDDABLE_GUARANTEED_DEAL
  • BACKFILL_DEAL
Deal types supported for a programmatic dealYesYesNoRequired when creating a new deal
external_deal_idstringempty, or <= 255 charactersA globally unique identifier.YesNoYesAn automatically generated external deal ID is returned when a deal is created.
namestring<= 255 charactersYesYesYesRequired when creating a new deal
descriptionstring<= 4096 charactersNoYesYesDefault is empty
salespersonstring<= 255 charactersNoYesYes
buyerssetSet<FW_ID>Buyers are invited on this deal to bid on an ad requestYesNoYesSize limit of 100 buyers per deal.

Required when pushing the deal setting
content_targetingContentTargetingYou can leverage the existing FreeWheel Inventory API:

- Video API v4.
- Site API v4
Inventory items targeted on the dealYesNoYes
ad_unitsAdUnitsAdUnitsAd units targeted on the dealYesNoYesSize 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
volumevolumeVolumeThe volume of the dealYesNoYesRequired when pushing deal detail settings
pricingpricingPricingThe price of the dealYesYesYesProgrammatic Guaranteed (PG): Must be fixed price

Others: Fixed or Floor price
schedulescheduleScheduleThe Schedule (start and end dates) of the dealYesNoYesRequired when pushing deal detail settings
statusstring
  • ACTIVE
  • INACTIVE (Default)
  • ARCHIVE/li>
  • PAUSE
  • COMPLETED
NoNoYesDefault is INACTIVE
max_ad_durationintegerAd duration in seconds, -1 means no limitNoNoYesDefault is -1
buyer_priority_overrideinteger[-1, 0, 1, ..., 10]Override the buyer priority for buyers behind this deal.

0 means do not override.
NoNoYesDefault 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.
NoNoNoPG: always True.

Default is False.
audience_targetingAudienceTargetingAudienceTargetingAudience items targeted on the dealNoNoYesThe maximum number of items for targeting is 4000.
platform_targetingPlatformTargetingPlatformTargetingPlatform items targeted on the dealNoNoYesThe maximum number of items for targeting is 4000.
geo_targetingGeoTargetingGeoTargetingGeo items targeted on the dealNoNoYesThe maximum number of items for targeting is 4000.
daypart_targetingDaypartTargetingDaypartTargetingDaypart items targeted on the dealNoNoYesThe maximum number of items for targeting is 4000.

7 * 24 by default
custom_targetingCustomTargetingCustomTargetingCustom items targeted on the dealNoNoYesThe maximum number of items for targeting is 4000.
isp_targetingsetSet<FW_ID>ISP items targeted on the dealNoNoYesThe maximum number of items for targeting is 4000.
brand_restrictionrestrictionRestrictionRestricted brands on the dealNoNoYesSize limit of 1000 brand restrictions per deal !!!

Using global brand items
advertiser_restrictionrestrictionRestrictionRestricted advertisers on the dealNoNoYesSize limit of 1000 advertiser restrictions per deal.

Using global advertiser items
banned_industrysetSet<FW_ID>Restricted industries on the deal industry-ids listNoNoYesYou cannot use the API for listing industries. You need to export the data from MRM.
vpaidbool
  • True
  • False
Indicated if VPAID is supported.NoNoYes
frequency_capFrequencyCapsFrequencyCapFrequency caps on the dealNoNoYesSupports a maximum of 3 frequency cap items
creative_approvalCreativeApprovalCreativeApprovalCreative approval type and clearance method for the dealNoNoYes
overrideoverrideFor 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
NoNoYesPG & 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.
ignore_brand_frequency_capbooleanYes

No
Indicate if brand frequency is ignoredNoNoYes
updated_atISO8601 UTCISO8601 UTC
global_agency_idsGlobalAgencyIdsGlobal agency associated to the dealNoNoYes
data_protection_package_idintegerData protection package on a dealNoNoYes
yield_optimizationYieldOptimizationYield optimisation on the dealNoNoYes
ssp_enablementbooleanTrue

False
This determines the activation of

SSP targeting in a deal
NoNoYes
ssp_content_targetingSame as ContentTargetingSame value as the deal Content Targeting.SSP inventory targeted on a dealNoNoYesThe following Content Standard Attributes are not supported in SSP Content Targeting:

Programmer, Brand, Channel, Content Daypart, Series
ssp_standard_attributes_targetingSSPStandardAttributesTargetingSSPStandardAttributesTargetingSSP standard attributes targeted on a dealNoNoYes
ssp_platform_targetingSame as PlatformTargetingSame value as the deal Platform TargetingSSP Daypart items targeted on the dealNoNoYes
ssp_geo_targetingSame as GeoTargetingSame value as the deal Geo TargetingSSP Platform items targeted on the dealNoNoYes
ssp_custom_targetingSame as CustomTargetingSame value as the deal Custom TargetingSSP Custom items targeted on the dealNoNoYes
ssp_audience_targetingSame as AudienceTargetingSame value as the deal Audience TargetingSSP Audience items targeted on the dealNoNoYes

SSPStandardAttributeItems

NodeData TypeValueDescriptionMandatory?
typeStringSSP Publisher
SSP Endpoint
SSP Channel
SSP IAB Category
SSP Standard Attributes types that can be targetedNo
idStringFW_IDID of corresponding SSP Standard attributes value that can be targetedNo

SSPStandardAttributesTargeting

NodeTypeMandatory?
includeSSPStandardAttributeItemsNo
excludeSSPStandardAttributeItemsNo

List API Objects

AdUnits

NodeData TypeValuesDescriptionMandatory
itemsSetad unitsAd units for the deal (eNo

Ad Unit

NodeData TypeValueDescriptionMandatory?
idFW_IDintegerFW_ID of the ad unitYes
statusenumACTIVE or
INACTIVE
Status of ad unit assignmentYes

Buyer List API

NodeData TypeValuesDescriptionMandatory?Comment
idFW_IDintegerFW_ID of the buyerYes
buyer_platformstring<= 255 charactersBuyer platform name of the buyerYes
trading_deskstring<= 255 charactersTrading desk name of the buyerYes
external_seat_idstringempty, or <= 255 charactersExternal seat id of the buyerYesThe default seat is empty.
updated_atISO8601 UTCISO8601 UTC
global_agency_idintegerGlobal Agency id associated to the buyerYes

Volume

NodeTypeValuesDescriptionMandatory?Comment
control_periodenum
  • DAY
  • MONTH
  • LIFECYCLE
The deal's impression goal periodYes
  • PG & BG only support per Life Cycle
  • FL, DEAL & BF support per DAY, MONTH, and LIFECYCLE
excess_delivery_curveenum
  • spiky-ext-none
  • spiky-ext-tiny
  • spiky-ext-conservative
  • spiky-ext-moderate
  • spiky-ext-aggressive
  • spiky-ext-unlimited
The deal's excess delivery settingNoOnly PG & BG support excess delivery
fixed_valueinteger0 ~ 2147483647The deal's fixed impression goalYes
  • PG & BG only support a fixed impression goal
  • FL, DEAL & BF support no limit and fixed impression goal
no_limitboolboolIt represents a deal with no limit.Yes
impression_goalstring0 ~ 2147483647The deal's fixed impression goalYesPG & BG only support a fixed impression goals.

FL, DEAL & BF support no limit and fixed impression goals.
excess_delivery_curveenum
  • 0%
  • 5%
  • 20%
  • 50%
  • 70%
  • UNLIMITED
    NETWORK_DEFAULT
Deal's excess delivery settingNoOnly PG & BG support excess delivery
control_paceenum
  • EVEN
  • AS_FAST_AS_POSSIBLE
  • CUSTOM
The deal's pacingYes
pacing_pointSetA set of pacing points. For each pacing point, you must have a date and a percentage.Valid when pacing = CUSTOM_PACING. The date should be follow ISO 8061 format in local timezone for POST requests, PUT requests and GET responses.

For example: 2013-09-04T10:59.

Note that ISO 8061 is not supported in Coordinated Universal Time (UTC).
Yes
time_zonestingSee MRM Time Zones

For example, (GMT-05:00) America - New York
A time zone for the dealYes

Pacing_point

NameTypeMandatory?
dateDateYes, when the control_pace value is CUSTOM_PACING
percentageDecimalYes, when the control_pace value is CUSTOM_PACING

Override

NodeTypeValuesDescriptionMandatory?Comment
modestringFor PG/BG:
  • ABOVE_PAYING_ADS
  • AMONGST_PAYING_ADS


For First Look, the mode is an empty string.
The override typeYesPG & BG support only.

For First Look deals, mode is meaningless.
valueinteger
  • 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 valueYes

Schedule

NodeTypeValuesDescriptionMandatory?Comment
start_timestringA time string such as 2021-01-01T00:00The start time of the dealYes
end_time

PG & BG: Required
Others: Optional
TimeA time stringThe end time of the deal
  • PG & BG: Required
  • Others: Optional
time_zonestringSee MRM Time ZonesThe time zone of the dealYes

Pricing

NodeTypeValuesDescriptionMandatory?Comment
modelenum
  • FIRST_FLOOR
  • SECOND_FLOOR
  • FIXED
The pricing model of the dealYesSECOND_FLOOR by default
pricedouble0.01 ~ 1,000,000.00The pricing valueYes
currency_overridestringUse currency code, such as CAD or USD.The currency to be used for the bidding.NoThis currency shares the global currency exchange rate with the network default currency.

CreativeApproval

NodeTypeValuesDescriptionMandatory?Comment
typeenum
  • NO_APPROVAL
  • GLOBAL
  • CLIENT
The approval typeYes
clearance_levelenum
  • PERMISSIBLE
  • RESTRICTED
The clearance typeYesPERMISSIBLE by default

FrequencyCaps

NodeTypeValuesDescriptionMandatory
itemsSetFrequency capsThe frequency caps of a dealNo

FrequencyCap

NodeTypeValuesDescriptionMandatory?
valueinteger< 2147483647The impression cap valueYes
periodintegerMinutes for Time ScopeThe cap period in minutesYes
typeenum
  • TIME
  • STREAM
  • ASSET
  • SITE_SECTION
  • LIFETIME
The cap axis optionsYes

ContentTargeting

NodeTypeDescriptionMandatory?
network_itemsContentTargetingNetworkItemsThe 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_attributesContentTargetingStandardAttributesThe 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
ronRonThe 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

ContentTargetingNetworkItems

NodeTypeMandatory?Description
includeTargetingSetsYesTargeting on raw Hylda Items is not supported in either the Programmatic Deal Open API or in the Marketplace user interface.
excludeTargetingItemsNo

ContentTargetingStandardAttributes

NodeTypeValues
includeStandardAttributeItemsYes
excludeStandardAttributeItemsNo

Ron

NodeTypeValuesDescriptionMandatory?
includeRonItemsRonItemsIncluded RON itemsYes

RonItems

NodeTypeValuesDescriptionMandatory?Comment
rovnboolean
  • True
  • False
Indicates whether ROVN is enabled or notYesDefault is False.
rosnboolean
  • True
  • False
Indicates whether ROSN is enabled or notYesDefault is False.
romnboolean
  • True
  • False
Indicates whether ROMN is enabled or notYesDefault is False.

GeoTargeting

NodeTypeValuesDescriptionMandatory?
includeGeoSetAtrributeGeoSetAtrributeGeographic attributes are included.No
excludeGeoSetAtrributeGeoSetAtrributeGeographic attributes are excluded.No

GeoSetAttribute

NodeTypeValuesDescriptionMandatory?
countrySetSet<FW_ID>
Country List
A set of FW ID of countriesNo
stateSetSet<FW_ID>; States, Provinces, and Regions ListA set of FW ID of statesNo
dmaSetSet<FW_ID>; US DMA ListA set of FW ID of DMAsNo
citySetSet<FW_ID>; Cities ListA set of FW ID of citiesNo
postal_codeSetSet<FW_ID>; Postal Code ListA set of FW ID of postal codesNo
postal_code_packageSetSet<FW_ID>; Postal Code ListA set of FW ID of postal code packagesNo
regionSetSet<FW_ID>; States, Provinces, and Regions ListA set of FW ID of regionsNo

ISPTargeting

NodeTypeValuesDescriptionMandatory?
includeSetSet<FW_ID>A set of FW ID of ISPsNo

CustomTargeting

NodeTypeValuesDescriptionMandatory?Comments
setsetSetIf there are multiple sets, then the relationship within a set can only be "ANY". Across sets, the relationship is "AND".NoNeed to confirm if the validation already exists or Targeting Service handles it
relation_between_setsSetSetIf 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

CustomTargetSet

NodeTypeValuesDescriptionMandatory?Comment
key_valueSetThe string value format is k=vA key-value setNoThe string value format =
relation_in_setsRelationTypeRelationTypeRelation in setsYes

AudienceTargeting

NodeTypeDescriptionMandatory?
includeTargetingSetsThe included audience itemsNo
excludeTargetingItemsThe excluded audience itemsNo

TargetingItems

NodeTypeValuesDescriptionMandatory?Comment
videoSet<FW_ID>Set of FW_IDFW ID set of videosNoOmit the node by default
video_groupSet<FW_ID>Set of FW_IDFW ID set of video groupsNoOmit the node by default
seriesSet<FW_ID>Set of FW_IDFW ID set of video seriesNoOmit the node by default
siteSet<FW_ID>Set of FW_IDFW ID set of siteNoOmit the node by default
site_sectionSet<FW_ID>Set of FW_IDFW ID set of site sectionNoOmit the node by default
site_groupSet<FW_ID>Set of FW_IDFW ID set of site groupNoOmit the node by default
site_section_groupSet<FW_ID>Set of FW_IDFW ID set of channelNoOmit the node by default
audience_itemSet<FW_ID>Set of FW_IDFW ID set of audience itemsNoOmit the node by default
relation_in_setRelationTypeRelationTypeThe relations in a setNoOmit the node by default

RelationType

NodeTypeValuesDescriptionMandatory?
relationenum
  • AND
  • OR
A relation typeYes

TargetingSets

NodeTypeDescriptionMandatory?
relation_between_setsSetThe relation between setsYes
setsSetThe set of targeting itemsYes
remaining_itemsTargetingItemsThe set of targeting itemNo

DaypartTargeting

NodeTypeDescriptionMandatory?Comments
time_zonestringA time zone nameYesFreeWheel provides a list of time zones
partSetA set of daypart targeting part (tick)YesMaximum size = 12

DaypartTargetingPart

NodeTypeValuesDescriptionMandatory?
start_timeenum'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 dayYes
end_timeenum'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 dayYes
start_dayenum
  • SUNDAY
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
The start day of a week repeated weeklyYes, when repeating daily
end_dayenum
  • SUNDAY
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
The end day of week repeated weeklyYes, when repeating daily
daysSet
  • SUNDAY
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
The repeated day of the weekYes, when repeating daily
repeatsenum
  • DAILY
  • WEEKLY
The repeated typeYes

PlatformTargeting

📘

Note

The standard_attributes node conflicts with the device, OS, browser, and package nodes. If the request passes through any of them with the node standard_attributes, an error is returned an error.

NodeTypeValuesDescriptionMandatory?
deviceSet <FW_ID>Valid Platform IDsNo
osSet <FW_ID>Valid Platform IDsNo
browserSet <FW_ID>Valid Platform IDsNo
packageSet <FW_ID>Obtained from MRMNo
standard_attributesSet of Standard Attributes inclusion and exclusion

PlatformTargetingStandardAttributes

NodeTypeValuesDescriptionMandatory?Comment
includeSet of Standard Attribute ItemsSet of Standard Attributes. Each Standard Attribute must contain a type and at least one ID.NoThe relationship between each Standard Attribute type is AND. The relationship between each Standard Attribute item under the same type is OR.
excludeSet of Standard Attribute ItemsSet of Standard Attributes. Each Standard Attribute must contain a type and at least one ID.NoThe relationship between each Standard Attribute type is AND. The relationship between each Standard Attribute items under the same type is OR.

StandardAttributeItems

NodeTypeValuesDescriptionMandatory?
standard_attributeSetSet of StandardAttributesEach Standard Attribute must contain a type and at least one IDYes

StandardAttributes

NodeTypeValuesDescriptionMandatory?Comment
typeenum
  • BRAND
  • DEVICE
  • OS
  • ENVIRONMENT
  • GENRE
  • PROGRAMMER
  • FORM
  • LANGUAGE
  • RATING
  • ENDPOINT_OWNER
  • ENDPOINT
Marketplace pre-defined standard attributes types that can be targetedYesPlatform SA:

  • DEVICE
  • OS
  • ENVIRONMENT
  • ENDPOINT_OWNER
  • ENDPOINT


Content SA:

  • GENRE
  • PROGRAMMER
  • FORM
  • LANGUAGE
  • RATING
  • BRAND
idsetSet<FW_ID>ID of corresponding Standard attributes value that can be targetedYesUse 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.

Restriction

NodeTypeValuesDescriptionMandatory
modeenum
  • ALLOW
  • BLOCK
Specifies the restriction modeYes
idSetSet<FW_ID>A set of FW ID of restricted items (brand, advertiser, or industry)Yes

GlobalAgencyIds

NodeTypeValuesDescriptionMandatoryComment
validBooleanTrue
False
Indicate if global agency is set for the dealYes
valueStringInteger ArrayGlobal agency id associated to the dealYes
(Only if Global agency is enabled i.e. valid = true)
If the network function GLOBAL_AGENCY is not enabled, then global_agency_ids field will be empty.

If the network function GLOBAL_AGENCY is enabled, but the global_agency_ids is not set, then global_agency_ids field = null.

If the network function GLOBAL_AGENCY is enabled and the global_agency_ids is set, then global_agency_ids field is an Integer Array.

Global Agency List API

NodeTypeValuesDescriptionMandatoryComment
idFW_IDintegerFreewheel's ID of the Global AgencyYes
nameString<= 255 charactersName of the Global AgencyYes
holding_company_idFW_IDintegerID of the holding company associated to the global agencyYes
holding_company_nameString<= 255 charactersName of the holding company associated to the global agencyYes

Data Protection Package List API

NodeTypeValuesDescriptionMandatoryComment
idFW_IDIntegerID associated to the data protection packageYes
nameStringName associated to the packageYes
scopeStringIMPRESSION_ONLY,
ALL_TRACKING_URL
Scope associated to the specified data protection packageYes
modeStringBLACKLIST, WHITELISTMode associated to the specified data protection packageYes
domainStringDomain associated to the specified data protection packageYes

YieldOptimization

NodeTypeValuesDescriptionMandatoryComment
volume_cap_modeStringIGNORE

INHERIT

OVERRIDE
Volume cap configuration associated to the dealYes
volume_cap_optimization_idsInteger ArrayConfiguration ID associated to the 'override' feature of volume cap. If the volume cap configuration is not 'override', then this value should be nullYes, when volume_cap_mode= OVERRIDE

No, for other values of volume_cap_mode
distribution_modeStringIGNORE

INHERIT

OVERRIDE
Distribution configuration associated to the dealYes
distribution_optimization_idIntegerID associated to the override feature of distribution. If the distribution configuration is not 'override', then this value should be nullYes, when distribution_mode= OVERRIDE

No, for other values of distribution_mode