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.
Function | Method Type | Description |
---|---|---|
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 |
Retrieve List of Advertisers | GET | Retrieves list of Advertisers, which can be sorted by days since last updated. |
Retrieve a list of Brands | GET | Retrieves list of Brands, which can be sorted by days since last updated. |
Activate a deal | PUT | Sets the deal status to activated |
Deactivate a deal | PUT | Sets 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
- 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..
Name | Type | Value | Description | Required for activation?? | Deal Creation API? | Deal Update API? | Notes |
---|---|---|---|---|---|---|---|
id | FW_ID | Integer | An integer number in FreeWheel | No | Yes | No | Not required when creating a new deal |
deal_type | enum |
| 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:
|
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 |
| 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 |
| 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 |
| 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:
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_cap | boolean | Yes No | Indicate if brand frequency is ignored | No | No | Yes | |
updated_at | ISO8601 UTC | ISO8601 UTC | |||||
global_agency_ids | GlobalAgencyIds | Global agency associated to the deal | No | No | Yes | ||
data_protection_package_id | integer | Data protection package on a deal | No | No | Yes | ||
yield_optimization | YieldOptimization | Yield optimisation on the deal | No | No | Yes | ||
ssp_enablement | boolean | True False | This determines the activation of SSP targeting in a deal | No | No | Yes | |
ssp_content_targeting | Same as ContentTargeting | Same value as the deal Content Targeting. | SSP inventory targeted on a deal | No | No | Yes | The following Content Standard Attributes are not supported in SSP Content Targeting: Programmer, Brand, Channel, Content Daypart, Series |
ssp_standard_attributes_targeting | SSPStandardAttributesTargeting | SSPStandardAttributesTargeting | SSP standard attributes targeted on a deal | No | No | Yes | |
ssp_platform_targeting | Same as PlatformTargeting | Same value as the deal Platform Targeting | SSP Daypart items targeted on the deal | No | No | Yes | |
ssp_geo_targeting | Same as GeoTargeting | Same value as the deal Geo Targeting | SSP Platform items targeted on the deal | No | No | Yes | |
ssp_custom_targeting | Same as CustomTargeting | Same value as the deal Custom Targeting | SSP Custom items targeted on the deal | No | No | Yes | |
ssp_audience_targeting | Same as AudienceTargeting | Same value as the deal Audience Targeting | SSP Audience items targeted on the deal | No | No | Yes |
SSPStandardAttributeItems
Node | Data Type | Value | Description | Mandatory? |
---|---|---|---|---|
type | String | SSP Publisher SSP Endpoint SSP Channel SSP IAB Category | SSP Standard Attributes types that can be targeted | No |
id | String | FW_ID | ID of corresponding SSP Standard attributes value that can be targeted | No |
SSPStandardAttributesTargeting
Node | Type | Mandatory? |
---|---|---|
include | SSPStandardAttributeItems | No |
exclude | SSPStandardAttributeItems | No |
List API Objects
AdUnits
Node | Data Type | Values | Description | Mandatory |
---|---|---|---|---|
items | Set | ad units | Ad units for the deal (e | No |
Ad Unit
Node | Data Type | Value | Description | Mandatory? |
---|---|---|---|---|
id | FW_ID | integer | FW_ID of the ad unit | Yes |
status | enum | ACTIVE or INACTIVE | Status of ad unit assignment | Yes |
Buyer List API
Node | Data Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
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. |
updated_at | ISO8601 UTC | ISO8601 UTC | |||
global_agency_id | integer | Global Agency id associated to the buyer | Yes |
Volume
Node | Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
control_period | enum |
| The deal's impression goal period | Yes |
|
excess_delivery_curve | enum |
| 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 |
|
no_limit | bool | bool | It represents a deal with no limit. | Yes | |
impression_goal | string | 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 |
| Deal's excess delivery setting | No | Only PG & BG support excess delivery |
control_pace | enum |
| The deal's pacing | Yes | |
pacing_point | Set | A 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_zone | sting | See MRM Time Zones For example, (GMT-05:00) America - New York | A time zone for the deal | Yes |
Pacing_point
Name | Type | Mandatory? |
---|---|---|
date | Date | Yes, when the control_pace value is CUSTOM_PACING |
percentage | Decimal | Yes, when the control_pace value is CUSTOM_PACING |
Override
Node | Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
mode | string | For PG/BG:
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 override value | Yes |
Schedule
Node | Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
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 |
| |
time_zone | string | See MRM Time Zones | The time zone of the deal | Yes |
Pricing
Node | Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
model | enum |
| 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. |
CreativeApproval
Node | Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
type | enum |
| The approval type | Yes | |
clearance_level | enum |
| The clearance type | Yes | PERMISSIBLE by default |
FrequencyCaps
Node | Type | Values | Description | Mandatory |
---|---|---|---|---|
items | Set | Frequency caps | The frequency caps of a deal | No |
FrequencyCap
Node | Type | Values | Description | Mandatory? |
---|---|---|---|---|
value | integer | < 2147483647 | The impression cap value | Yes |
period | integer | Minutes for Time Scope | The cap period in minutes | Yes |
type | enum |
| The cap axis options | Yes |
ContentTargeting
Node | Type | Description | Mandatory? |
---|---|---|---|
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 |
ContentTargetingNetworkItems
Node | Type | Mandatory? | Description |
---|---|---|---|
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 |
ContentTargetingStandardAttributes
Node | Type | Values |
---|---|---|
include | StandardAttributeItems | Yes |
exclude | StandardAttributeItems | No |
Ron
Node | Type | Values | Description | Mandatory? |
---|---|---|---|---|
include | RonItems | RonItems | Included RON items | Yes |
RonItems
Node | Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
rovn | boolean |
| Indicates whether ROVN is enabled or not | Yes | Default is False. |
rosn | boolean |
| Indicates whether ROSN is enabled or not | Yes | Default is False. |
romn | boolean |
| Indicates whether ROMN is enabled or not | Yes | Default is False. |
GeoTargeting
Node | Type | Values | Description | Mandatory? |
---|---|---|---|---|
include | GeoSetAtrribute | GeoSetAtrribute | Geographic attributes are included. | No |
exclude | GeoSetAtrribute | GeoSetAtrribute | Geographic attributes are excluded. | No |
GeoSetAttribute
Node | Type | Values | Description | Mandatory? |
---|---|---|---|---|
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 |
ISPTargeting
Node | Type | Values | Description | Mandatory? |
---|---|---|---|---|
include | Set | Set<FW_ID> | A set of FW ID of ISPs | No |
CustomTargeting
Node | Type | Values | Description | Mandatory? | Comments |
---|---|---|---|---|---|
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 |
CustomTargetSet
Node | Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
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 |
AudienceTargeting
Node | Type | Description | Mandatory? |
---|---|---|---|
include | TargetingSets | The included audience items | No |
exclude | TargetingItems | The excluded audience items | No |
TargetingItems
Node | Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
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 |
RelationType
Node | Type | Values | Description | Mandatory? |
---|---|---|---|---|
relation | enum |
| A relation type | Yes |
TargetingSets
Node | Type | Description | Mandatory? |
---|---|---|---|
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 |
DaypartTargeting
Node | Type | Description | Mandatory? | Comments |
---|---|---|---|---|
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 |
DaypartTargetingPart
Node | Type | Values | Description | Mandatory? |
---|---|---|---|---|
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 |
| The start day of a week repeated weekly | Yes, when repeating daily |
end_day | enum |
| The end day of week repeated weekly | Yes, when repeating daily |
days | Set |
| The repeated day of the week | Yes, when repeating daily |
repeats | enum |
| The repeated type | Yes |
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 nodestandard_attributes
, an error is returned an error.
Node | Type | Values | Description | Mandatory? |
---|---|---|---|---|
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 |
PlatformTargetingStandardAttributes
Node | Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
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. |
StandardAttributeItems
Node | Type | Values | Description | Mandatory? |
---|---|---|---|---|
standard_attribute | Set | Set of StandardAttributes | Each Standard Attribute must contain a type and at least one ID | Yes |
StandardAttributes
Node | Type | Values | Description | Mandatory? | Comment |
---|---|---|---|---|---|
type | enum |
| Marketplace pre-defined standard attributes types that can be targeted | Yes | Platform SA:
Content SA:
|
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. |
Restriction
Node | Type | Values | Description | Mandatory |
---|---|---|---|---|
mode | enum |
| Specifies the restriction mode | Yes |
id | Set | Set<FW_ID> | A set of FW ID of restricted items (brand, advertiser, or industry) | Yes |
GlobalAgencyIds
Node | Type | Values | Description | Mandatory | Comment |
---|---|---|---|---|---|
valid | Boolean | True False | Indicate if global agency is set for the deal | Yes | |
value | String | Integer Array | Global agency id associated to the deal | Yes (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
Node | Type | Values | Description | Mandatory | Comment |
---|---|---|---|---|---|
id | FW_ID | integer | Freewheel's ID of the Global Agency | Yes | |
name | String | <= 255 characters | Name of the Global Agency | Yes | |
holding_company_id | FW_ID | integer | ID of the holding company associated to the global agency | Yes | |
holding_company_name | String | <= 255 characters | Name of the holding company associated to the global agency | Yes |
Data Protection Package List API
Node | Type | Values | Description | Mandatory | Comment |
---|---|---|---|---|---|
id | FW_ID | Integer | ID associated to the data protection package | Yes | |
name | String | Name associated to the package | Yes | ||
scope | String | IMPRESSION_ONLY, ALL_TRACKING_URL | Scope associated to the specified data protection package | Yes | |
mode | String | BLACKLIST, WHITELIST | Mode associated to the specified data protection package | Yes | |
domain | String | Domain associated to the specified data protection package | Yes |
YieldOptimization
Node | Type | Values | Description | Mandatory | Comment |
---|---|---|---|---|---|
volume_cap_mode | String | IGNORE INHERIT OVERRIDE | Volume cap configuration associated to the deal | Yes | |
volume_cap_optimization_ids | Integer Array | Configuration ID associated to the 'override' feature of volume cap. If the volume cap configuration is not 'override', then this value should be null | Yes, when volume_cap_mode= OVERRIDE No, for other values of volume_cap_mode | ||
distribution_mode | String | IGNORE INHERIT OVERRIDE | Distribution configuration associated to the deal | Yes | |
distribution_optimization_id | Integer | ID associated to the override feature of distribution. If the distribution configuration is not 'override', then this value should be null | Yes, when distribution_mode= OVERRIDE No, for other values of distribution_mode |