---
title: "OpenRTB Supply Integration Guide - ortb/ssp"
canonical: "https://hub.freewheel.tv/space/RCS/424378397/OpenRTB%20Supply%20Integration%20Guide%20-%20ortb%2Fssp"
format: markdown
---
Specification Support Specification Version Last Update Date Notes OpenRTB v2.5 with oRTB 2.6 Dynamic Podding support** Unsupported Attributes All unsupported OpenRTB attributes included in OpenRTB Supply Ad Requests will be ignored by Freewheel systems. Not all oRTB 2.5 attributes are supported, please see what's supported in the relevant object tables. If you do not see a OpenRTB attribute listed in the relevant object table then it is not supported . **See section 5.12 Video Object for specifics on what attributes are supported for Dynamic Podding as not all attributes are supported. IAB Content Category Taxonomy v1 For a reference to the IAB Content Category Taxonomy we support please see here: IAB Content Category Taxonomy V1 IAB Content Categories are mapped to FreeWheel Global Industries. Guide Change Log Current Guide Version Guide Version Date Author Description v3.97 Admin Section 1.2 - Features at-a-glance Removed " Dynamic Ad Podding cannot be active at the same time as Multi-bid or Multi-Imp" Historic Version Date Author Description v3.96 Admin Section 5.11 - Regs Object Added ext.dsa object Section 5.15 - Ext Object Added ext.dsa object Section 6.3 - Bid Object Added ext.dsa object Added clarification note around bid.ext.dealid Section 6.4 - Ext Object Added ext.dsa object Added clarification note around bid.ext.dealid v3.95 Admin Section 5.1.1 - Site Section ID Added a note stating that only passing one Site Section ID is supported for multi-imp requests v3.94 Admin Section 4.4.3 User-matching corrected typo on user sync url http:/ to http:// v3.93 Admin Section 1.2 - Features at-a-glance Removed verbiage stating that multi-bid was enabled by default Replaced with Must be requested to Freewheel Account Team to review and enable v3.92 Admin Section 5.12 - Video Object plcmnt description updated to clarify what plcmnt types are supported placement description updated to clarify what placement types are supported v3.9 Admin Section 4.4.3 - User Sync matching Changed User Sync URL to http:// from https:// v3.8 Admin Section 5 Name Changed name to 'Ad Request Body' from 'Bid Request Body' Section 5.3 Name Changed name to 'AdRequest Body' from 'BidRequest Body' Replaced 21 instances of the term 'bid request' with 'ad request' Replaced 18 instances of the term 'bidrequest' with 'adrequest' v3.7 Admin Section 4.4.3 Updated section to provide more details on this process Created steps to provide overview of how the user sync process works from FreeWheel's perspective Removed language regarding FW providing a sync URL for implementation and replaced it with a note that the user synch process runs off of auto sync Section 5.13 Changed scope of country attribute from 'Mandatory' to 'Recommended' Section 5.3 Changed scope of regs object from 'Mandatory' to 'Recommended' v3.6 Admin Removed "sequence" field from both App and Site request examples v3.5 Admin Section 5.17 - Standard Attributes for Inventory Standardization Added new section Features at-a-glance Removed third point under Dynamic Ad Podding and added that it will be automatically detected in the request Removed points in multi-bid and multi-imp stating that it cannot be active at the same time as Dynamic Ad Podding Section 5.14 - Content Object Added content.ext.network v3.4 Admin Section 6.3 - Bid Object dspid type changed to integer Section 6.4 - Ext Object dspid type changed to integer v.3.3 Admin Section 4.4.3 - User-Matching Added support of additional privacy parameters Section 6.3 - Bid Object added extension fields for dealid and dspid Section 6.4 - Ext Object added extension fields for dealid and dspid v3.2 Admin Section 4.4.3 - User Matching Added description and required actions to setup user sync Section 5.1.3 - Profile ID Added language on fallback network profile v3.1 Admin Section 1.2 - Features at a Glance Clarified that FreeWheel also supports single imp requests. Section 4.2 - Endpoint clarified wording of endpoint prefix ID Section 4.6 - Gzip Support added section to clarify current Gzip compression support Section 5.6 - Site Object added ext.inventorypartnerdomain field as supported Section 5.7 - App Object added more detailed description for ext.inventorypartnerdomain clarified the 'mandatory' scope of the app.storeurl object v3.0 Admin Section 5.12 - Video Object Updated placement & plcmt field to indicate we currently only support the value of 1 Section 5.1.3 - Profile ID Typo correction Section 5.14 - Content Object Added support for content.ext.channel field Section 5.15 - Ext Object Added support for content.ext.channel field Section 5.6 - App Object added publisher object v2.9 Admin Section 7 - Response Codes Included extra response code 403 Section 5.16 - Keywords Object Custom Key-Value Pairs now accepted as lists _fw_content_programmer_brand_channel example updated _fw_content_language example updated _fw_content_rating example updated _fw_content_stream_mode example updated _fw_platform example updated v2.8 Admin Section 5.10 - Source Object Included extra context for schain object's scope. Section 5.6 - App Object app.ver scope changed from mandatory to recommended Section 1.2 - Features at a glance Clarified wording Section 5.3 - AdRequest Object added ext.fw_gd field Section 5.4 - Imp Object added ext.fw_gd field Section 5.16 - Keywords Object Added _fw_content_programmer_brand_channel Added _fw_content_language Added _fw_content_rating Added _fw_content_stream_mode Added _fw_platform v2.7 Admin Section 5.1.1 - Site Section ID ext.custom_site_section_id Made changes to account additional support for using numeric Site Section ID values imp[0].ext.custom_site_section_id Made changes to account additional support for using numeric Site Section ID values Section 5.8 - Device Object device.ua Support released to detect device.ua as the user agent by FW systems, no longer required to pass user agent in ad request headers. Section 5.14 - Content Obect content.genre Made changes to account for newly released support of content.genre to be detectable as a Genre Standard Attribute. Section 5.16 - Keywords Object _fw_content_genre Removed information stating the it was the only option for Genre Standard Attribute detection. content.genre is now supported detection. v2.5 Admin Specification Support Added clarification on unsupported attributes not listed on this guide. Unsupported attributes will be ignored by Freewheel systems. Section 3 - Publisher Pre-requisites Clarification to first line requirement. Changed "Previously existing SFX Private Exchange" to "Be a Freewheel SSP client". v2.4 Admin Add Specification Support Table Section 1.1 - Intro Brief updated with more context over the purpose of the integration and added a high level overview diagram of the integration Section 1.2 - Features at-a-glance Features at-a-glance table added to highlight specific features that can be enabled on top of the base oRTB-S integration. Section 5.1.1 - Site Section ID app.id - comments amended to "For app inventory only. The value could be a custom Site Section tag or numeric Site Section ID." site.id - comments amended to "For web inventory only. The value could be a custom Site Section tag or numeric Site Section ID." Section 4.5 - Request 'tmax' Request 'tmax' section added to provide context on recommended tmax settings. Section 5.5 - Site Object site.id - comments amended to "Mandatory, if inventory being passed is web inventory and if the request is not passing ext.custom_site_section_id or imp[0].ext.custom_site_section_id" Section 5.6 - App Object app.id - comments amended to Mandatory, if inventory being passed is app inventory and if the request is not passing ext.custom_site_section_id or imp[0].ext.custom_site_section_id Section 5.12 - Video Object Context added to Video Object description " oRTB 2.6 Dynamic Podding is supported, however, not all attributes are supported. See the table for what attributes are supported." podid - removed Section 5.14 - Content Object content.genre comments amended to describe lack of detection support for the Genre Standard Attribute. To use keywords _fw_content_genre until support is released in Freewheel SSP version 7.7. Section 5.16- Keywords Object _fw_content_genre line item added. Describes support for passing genre values to be detected to dynamically pass Genre Standard Attributes. v2.3 Admin Added sample podded request and response Section 5.6 ext.inventorypartnerdomain - Scope amended to 'Mandatory (for CTV publishers with content partners)' Section 5.12 maxseq - Scope amended to 'Optional (Mandatory if using dynamic ad podding)' poddur - Scope amended to 'Optional (Mandatory if using dynamic ad podding)' v2.2 Admin Amended language for Section 4.2 Endpoint Minor wording/structural changes v2.1 Admin Minor wording/structural changes 1. Introduction 1.1 Brief The FreeWheel OpenRTB Supply Integration API (oRTB-S) has been created in order to make it possible to deploy and maintain an effective OpenRTB supply integration with Freewheel to pass inventory to downstream demand sources to obtain incremental demand. This page is intended only for customers with FWSSP paperwork, ad servers that are utilized by FWSSP customers, or other validated use cases . ORTB is a standard that was created by the IAB for the purpose of creating a universal language that all entities participating in an auction can speak in order to conduct business. Auctions are the backbone of programmatic advertising and ensure that publishers are earning the highest possible price for their ad space. You can find more information on the ORTB 2.5 specification here . The FreeWheel oRTB-S integration has been implemented using the oRTB 2.5 Standard with support for oRTB 2.6 dynamic podding. To further clarify, not all attributes from the 2.5 and 2.6 specs are supported, to assure which ones are supported please see the individual object tables below. This ensures compliance with the common data structure and communication layers of ORTB. For a complete list of mandatory, recommended and optional fields available within the Freewheel API, please refer to the Ad Request section of this guide. 1.2 Features at-a-glance The FreeWheel OpenRTB Supply API supports the below key features. Please note that FreeWheel also supports single impression ORTB 2.5 requests and single bid responses. However, we recommend using a combination of the below features for increased efficiency and performance. Feature Note(s) Dynamic Ad Podding Under ORTB 2.6 spec (see Video Object ) Will automatically be detected in the request if dynamic podding is available Multi-Bid Up to 5 bids supported per ad request imp object Must be requested to Freewheel Account Team to review and enable Multi-Imp (Structured Podding) Up to 5 imp objects supported per ad request Must be requested to Freewheel Account Team to review and enable 2. Pre-integration steps Prior to the start of the integration, publishers must provide to their account team the following: Server locations from publishers Pingable (responsive to ICMP) external IP addresses from each respective server location. This is to enable our engineers to test Round Trip Time. (Alternatively you can run a test yourself once the ORTB Module has been enabled on your Network: see Section 4.2 Endpoint below) Estimated traffic per geo Daily max QPS and average QPS The ad-server you are using Following approval from the Freewheel account team, FreeWheel resources will enable the oRTB-S integration on your network and provide you the necessary key values for operation. 3. Publisher Pre-requisites Be a Freewheel SSP Client Network Endpoint Prefix ID Network-specific custom end-point Network ID Profile ID Site Section ID(s) User matching URL (for web inventory) - Provided by Freewheel User sync redirect URL (for web inventory) - provided by publisher 4. Configuration 4.1 Data Centres The Freewheel ORTB servers cover three geographical zones: Europe US-East US-West 4.2 Endpoint Publishers will be provided with a unique endpoint for which to send requests. Endpoints will have a variable En dpoint Prefix ID which is the Network ID (see Glossary) in hexadecimal format. This Endpoint Prefix ID will need to be added as a prefix within the URL. Format : https://prefix .v.fwmrm.net/ortb/ssp Example with a custom prefix included : https:// 83b9 6 .v.fwmrm.net/ortb/ssp If you have not supplied us with your pingable server IP addresses, you can run a test against the custom end-point with the following command and provide us with the results : mtr --report-wide --report-cycles=200 -nTP 443 https: // [your_custom_prefix]. v.fwmrm.net/ortb/ssp 4.3 Response The oRTB-S API will respond with a status code . For successful auctions, creative information and CPM will be included in the response. See Bid Response section for more information. 4.4 User Syncing 4.4.1 Non-Cookie Environments For in-app and OTT environments, we use the device IFA which does not need to be synced between the publisher and Freewheel. These can be passed directly in the ad request. 4.4.2 Cookie-Based Environments *This section is only necessary for web inventory User Syncing, also known as Cookie Syncing, is the process of sharing and matching HTTP cookies between various partners. The concept of Cookie Tracking is restrictive in the amount of information that can be collected and actioned upon for advertisers. This is because cookies are limited to domain and have varying expiration dates. In order for Freewheel to be able to identify, target and frequency cap across various digital properties in accordance with campaign KPI's, Freewheel needs to know how to distinguish one user from another that are sent to us in the publisher's ad request. 4.4.3 User-matching *This section is only necessary for web inventory FreeWheel supports a supply-initiated user sync process where the upstream ad server is responsible for hosting the matching table. FreeWheel will include an auto user sync pixel in the ad response. When fired, it redirects to your sync URL and passes FreeWheel's user ID for matching . Please note: Freewheel, in the ad response, will provide the below sync url which will redirect to the ad server's sync URL, providing the FreeWheel user ID. FreeWheel requires that incoming oRTB-S requests from the ad server for web inventory contain the user.buyeruid field populated with FreeWheel's user/cookie ID FreeWheel currently supports the below privacy URL parameters appended to the sync URL &gdpr=xxx&gdpr_consent=xxx&us_privacy=xxx&gpp=xxx&gpp_sid=xxx&_fw_is_lat=xxx&_fw_atts=xxx&_fw_coppa=xxx The matching table that must be hosted by the ad server will create the linking between client cookies and Freewheel cookies *There are a couple of requirements in setting up user sync Ad server domain needs to be allow listed with FreeWheel. For this, please reach out to your FreeWheel Account Manager. Input the ad server domain into the cr parameter of the FreeWheel sync pixel. Please note that the URL to be redirected to will need to be percent encoded in practice : http://user-sync.fwmrm.net/ad/u?mode=echo&cr=https://www.yourdomain.com/fw-syncpixel.gif?_uid=#{user.id} 4.5 Request 'tmax' In order to avoid timeouts and to accommodate downstream hops, we highly recommend that a tmax of at least 500ms is passed in the ad request. In cases where this not possible to change, please inform your Freewheel point of contact in order to assess how we can best manage this and avoid any technical implications. 4.6 Gzip Compression Support FreeWheel OpenRTB-S supports gzip compression of ad requests and responses. Gzipped requests must indicate their encoding via header: Content-Encoding: gzip FreeWheel also supports gzipped responses. If the request contains the header: Accept-Encoding: gzip And response body size > 128 bytes, FreeWheel will gzip the response and provide header: Content-Encoding: gzip Please speak with the FreeWheel team before enabling gzip requests. 5. Ad Request Body 5.1 Freewheel Specific IDs This section covers the Freewheel-specific core fields that need to be passed in order for the request to be processed successfully. 5.1.1 Site Section ID Site Section ID is a placement identifier that is used as the most granular way to segment ad retrieval. Requests must contain a Site Section ID. For multi-imp requests, only one Site Section ID is supported. Passing multiple objects with different Site Section IDs is not supported Attribute Type Priority (From high to low) Example Comment(s) Scope ext.custom_site_section_id object.string 1 "ext": { "custom_site_section_id": "ss_12345" } The value should be a custom Site Section tag or numeric Site Section ID. Mandatory - request must contain one of these values imp[0].ext.custom_site_section_id object.string 2 "ext": { "custom_site_section_id": "ss_12345" } The value should be a custom Site Section tag or numeric Site Section ID. app.id object.string 3 "app": { "id": "ss_abcd12345" } -or- "app": { "id": "12345" } For app inventory only The value could be a custom Site Section tag or numeric Site Section ID. site.id object.string 3 "site": { "id": "ss_abcd12345" } -or- "site": { "id": "12345" } For web inventory only The value could be a custom Site Section tag or numeric Site Section ID. 5.1.2 Network ID Distributor's FreeWheel network ID. Requests must contain a Network ID. Attribute Type Priority (From high to low) Example Comment(s) Scope ext.network_id object.string 1 "ext": { "network_id": "12345" } This value should be numeric Network ID Mandatory - request must contain one of these values imp[0].ext.network_id object.string 2 "ext": { "network_id": "12345" } This value should be numeric Network ID publisher.id object.string 3 "publisher": { "id": "12345" } This value should be numeric Network ID 5.1.3 Profile ID Profile name indicating configurations such as creative restrictions and compliance related settings. If no value is passed, the fallback Network Profile will be used Attribute Type Priority (From high to low) Example Comment(s) Scope ext.profile_id object.string 1 "ext": { "profile_id": "12345:profile_name" } -or- "ext": { "profile_id": "profile_name" } The value should contain a profile name. and NOT a numeric profile ID. This can either include the network ID prefix (first example) or with the profile name alone (second example). Recommended - one of these values should be passed (If no value is passed, the Network Profile will be used) imp[0].ext.profile_id object.string 2 "ext": { "profile_id": "12345:profile_name" } -or- "ext": { "profile_id": "profile_name" } The value should contain a profile name. and NOT a numeric profile ID. This can either include the network ID prefix (first example) or with the profile name alone (second example). 5.2 Passing User/Device ID For app and CTV inventory, the user ID to pass in the ad request is the Device ID in device.ifa. For web inventory, the ID to pass in the ad request is the Freewheel User ID that has previously been synced (see Section 4.4 above). It must be passed in user.buyeruid. 5.3 AdRequest Object The top-level ad request object contains a globally unique ad request ID. This id attribute is required alongside at least one impression object. Some other subordinate objects are also required: Site or App, depending on whether the content is browser-based or originating from a non-browser application such as mobile app or CTV app. Other required subordinate objects are Device and User. Attribute Type Device Description Example Scope id string app/web Unique ID of the ad request. "id": "892_1680798316567031-361_2_1086066" Mandatory imp object array app/web Array of Imp objects representing the impressions offered. see Imp Object Mandatory site object web Details via a Site object about the publisher's website. see Site Object Mandatory (for Web) app object app Details via an App object about the publisher's app. see App Object Mandatory (for app/OTT) device object app/web Details via a Device object about the user’s device to which the impression will be delivered. see Device Object Mandatory user object app/web Details via a User object about the human user of the device; the advertising audience. see User Object Mandatory cur string array app/web Array of allowed currencies for bids on this ad request using ISO-4217 alpha codes. "cur": [ "EUR", "AUD", "JPY", "GBP", "DKK", "CAD", "USD", "SEK", "NOK" ] Recommended tmax integer app/web Maximum time in milliseconds to submit a bid to avoid timeout. See 4.5 Request 'tmax ' on the recommended tmax value. "tmax": 500 Mandatory source object app/web A Source object that provides data about the inventory source and which entity makes the final decision. see Source Object Recommended bcat string array app/web Blocked advertiser categories using the IAB Categories v1.0. "bcat": [ "IAB17-18", "IAB23", "IAB11", "IAB7-39", "IAB26", "IAB25", "IAB24", "IAB9-9" ] Recommended regs object app/web A Regs object that specifies any industry, legal, or governmental regulations in force for this request. See Regs Object Recommended at Integer app/web Auction Type. 1 - first price auction, 2 - second price auction "at": 1 Recommended Only 1st price auction is supported. ext.keywords object.object app/web This object can be used to pass through custom fields and additional value-enhancing information see Keywords Object Optional ext.custom_site_section_id object.string app/web Site section ID to be passed in the ext object as a string if it cannot be passed in the site or app object id field. "ext": { "custom_site_section_id": "ss_12345" } Mandatory if not passed via imp[0].ext.custom_site_section_id or site.id or app.id ext.profile_id object.string app/web Profile name to be passed in the ext object as string. ( If not passed, use network profile) "ext": { "profile_id": "12345:xxx_ios" } Recommended ext.network_id object.string app/web Network ID to be passed in the ext object as string "ext": { "network_id": "12345" } Mandatory if not passed via imp[0].ext.network_id or publisher.id ext.fw_gd integer app/web Indicates if the inventory is guaranteed from ad-server side for guaranteed demand from FreeWheel. 1 - guaranteed, 0 (default) - Not guaranteed. Note that guaranteed inventory should be sent in its own ad request. Any publisher passing this field with a value of 1 should first consult with FreeWheel to ensure correct setup for guaranteed demand has been done. "fw_gd": 1 Mandatory for programmatic guaranteed transactions. May also be passed in the Imp object. 5.4 Imp Object Within the main AdRequest object, the Imp object describes an ad placement or impression being auctioned. A single ad request can include multiple Imp objects. Each Imp object has a required ID so that bids can reference them individually. The Video subordinate object is required, as is the Secure object Attribute Type Device Description Example Scope id string app/web A unique identifier for this impression within the context of the ad request. "id": "1" Mandatory video object app/web A Video object see Video Object Mandatory bidfloor float app/web Minimum bid for this impression expressed in CPM. If there are multiple imp objects in the request, only the value from the first imp will be honoured "bidfloor": 6.5603 Recommended bidfloorcur string app/web Currency specified using ISO-4217 alpha codes. If there are multiple imp objects in the request, only the value from the first imp will be honoured "bidfloorcur": "USD" Recommended secure integer app/web Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. "secure": 1 Mandatory ext.custom_site_section_id object.string app/web Site section ID to be passed in the ext object as a string if it cannot be passed in the site or app object id field. If there are multiple imp objects in the request, only the value from the first imp will be honoured "ext": { "custom_site_section_id": "ss_12345" } Mandatory if not passed via ext.custom_site_section_id or site.id or app.id ext.profile_id object.string app/web Profile ID to be passed in the ext object as string If there are multiple imp objects in the request, only the value from the first imp will be honoured "ext": { "profile_id": "12345" } Recommended ext.network_id object.string app/web Network ID to be passed in the ext object as string If there are multiple imp objects in the request, only the value from the first imp will be honoured "ext": { "network_id": "12345" } Mandatory if not passed via ext.network_id or publisher.id ext.fw_gd integer app/web Indicates if the inventory is guaranteed from ad-server side for guaranteed demand from FreeWheel. 1 - guaranteed, 0 (default) - Not guaranteed. Note that guaranteed inventory should be sent in its own ad request. Any publisher passing this field with a value of 1 should first consult with FreeWheel to ensure correct setup for guaranteed demand has been done. "fw_gd": 1 Mandatory for programmatic guaranteed transactions. May also be passed in the AdRequest object. 5.5 Site Object Within the main AdRequest object, the Site object should be included if the ad supported content is a website as opposed to a non-browser application. You should pass the ID of the Site Section for web inventory as site.id if possible. Attribute Type Device Description Example Scope id string web The numeric site section ID or custom site section tag. "id": "2513073" or "id": "site id" Mandatory, if inventory being passed is web inventory and if the request is not passing ext.custom_site_section_id or imp[0].ext.custom_site_section_id domain string web Domain of the site. "domain": "testortb.com" Recommended ref string web Referrer URL that caused navigation to the current page. "ref": "https://www.google.com" Recommended cat string array web Array of IAB categories for the site using IAB Categories v1.0. "cat": [ "IAB1" , "IAB9-1", "IAB9-25"] Recommended page string web URL of the page where the impression will be shown. "page": "https://testortb.com/pagepath" Optional content object web Details about the Content within the site. see Content Object Optional name string web Site name "name": "Dailymotion" Optional publisher object web Details about the publisher of the site see Publisher Object Optional ext.inventorypartnerdomain object.string web inventorypartnerdomain declaration for ads.txt "ext": { "inventorypartnerdomain": "inventorypartnerdomain_example.com" } Mandatory (for CTV publishers with content partners) For more information please see IAB guidance for including inventorypartnerdomain: IAB Guidance for Inventory Sharing 5.6 App Object Within the main AdRequest object, the App object should be included if the ad supported content is a non-browser application (mobile app or CTV app) as opposed to a website. You should pass the ID of the Site Section for app inventory as app.id if possible. Attribute Type Device Description Example Scope id string app The numeric site section ID or custom site section tag. "id": "26781922" or "id": "application id" Mandatory, if inventory being passed is app inventory and if the request is not passing ext.custom_site_section_id or imp[0].ext.custom_site_section_id name string app App name "name": "Golf Clash" Mandatory ver string app App version "ver": "2.46.1" Recommended bundle string app Bundle or package name or ID "bundle": "1089225191" Mandatory storeurl string app App store URL for an installed app. "storeurl": "https://itunes.apple.com/app/id1089225191" Mandatory (for apps/platforms that have app stores) content object app Details about the Content within the app. see Content Object Recommended cat string array app Array of IAB categories of the app using IAB Categories v1.0. "cat": [ "IAB1" , "IAB9-1", "IAB9-25"] Recommended publisher object app Details about the publisher of the app see Publisher Object Optional ext.inventorypartnerdomain object.string app inventorypartnerdomain declaration for ads.txt "ext": { "inventorypartnerdomain": "inventorypartnerdomain_example.com" } Mandatory (for CTV publishers with content partners) For more information please see IAB guidance for including ext.inventorypartnerdomain: IAB Guidance for Inventory Sharing 5.7 Publisher Object Attribute Type Device Description Example Scope id string web/app Pass Freewheel Network ID to this field "id": "26781" Recommended (Mandatory if not passed via ext.network_id or imp[0].ext.network_id) 5.8 Device Object Within the main AdRequest object, the device object provides information pertaining to the device through which the user is interacting. Device information includes its hardware, platform, location, and carrier data. The device can refer to a mobile handset, a desktop computer, set top box, or other digital device. Attribute Type Device Description Example Scope ua string app/web Browser user agent string. Support released to detect device.ua as the user agent by FW systems, no longer required to pass user agent in ad request headers. "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_1_1 like Mac OS X) AppleWebKit / 605.1 .15(KHTML, like Gecko) Mobile / 15E148" Mandatory ip string app/web IPv4 address closest to device. "ip": "31.94.25.0" Mandatory devicetype integer app/web The general type of device. Supported device types are PC = 2, CONNECTED_TV = 3, PHONE = 4, TABLET = 5, SET_TOP_BOX = 7 "devicetype": 4 Mandatory ifa string app/web ID sanctioned for advertiser use in the clear (i.e., not hashed). "ifa": "15141656-d6ac-056e-f349-a751d607bfd7" Recommended make string app/web Device make. "make": "Apple" Recommended model string app/web Device model. "model": "iPhone" Recommended geo object app/web Device/user location see Geo Object Recommended lmt integer app/web “Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines "lmt": 1 Optional ipv6 string app/web IP address closest to device as IPv6. "ipv6": "::ffff:31.94.25.0" Optional language string app/web Browser language using ISO-639-1-alpha-2. "language": "en" Optional ext.lmt object.integer app/web “Limit Ad Tracking” signal passed as external object attribute, commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines "ext": { "lmt": 1 } Optional - not recommended. lmt preferred. ext.ifv object.string app/web Device identifier for vendors "ext": { "ifv": "336F2BC0-245B-4242-8029-83762AB47B15" } Recommended ext.atts object.integer app/web Indicates Apple’s App Tracking Authorization status. "ext": { "atts": 1 } Recommended ext.ifa_type object.string app/web IAB Recommended values for ifa_type : dpid - the generic “device provided id”, but based on historical usage, common device type specific values can be used. rida - Roku id aaid - Android id idfa - Apple id afai - Amazon Fire id msai - Microsoft id ppid - publisher provided id sspid - SSP provided id sessionid - session id / synthetic id "ext": { "ifa_type": "idfa" } Recommended 5.9 User Object Within the main AdRequest object, the User object contains information known or derived about the human user of the device (i.e., the audience for advertising). Attribute Type Device Description Example Scope buyeruid string web User ID for web/mobile-web inventory "buyeruid": "fe2e81168df3c1b6ebfe481e9eb3d99" Mandatory for Web ext.consent object.string app/web Encoded user consent string based on GDPR Consent Working Group structure "ext": { "consent": "BOSSotLOSSotLAPABAENBc-AAAAgR7_______9______9uz_Gv_v_f__33e8__9v_l_7_-___u_-33d4-_1vX99yfm1-7ftr3tp_86ues2_XqK_9oIiA" } Recommended ext.gdpr object.integer app/web GDPR applied or not "ext": { "gdpr": 1 } Recommended ext.eids object.object app/web External IDs for synching purposes. "eids": [{ "source": "id5 - sync.com", "uids": [{ "ext": { "linkType ": 1 }, "id": "hashed_id", "atype": 1 } ] }, { "source": "criteo.com", "uids": [{ "id ": "hashed_uid ", "atype": 1 } ] } ] Recommended 5.10 Source Object Within the main AdRequest object, the Source object describes the nature and behavior of the entity that is the source of the ad request upstream from the exchange. Attribute Type Device Description Example Scope ext.schain object.object app/web Supply Chain information and an array of nodes. "ext ": { "schain": { "complete": 1, "nodes": [{ "asi": "ad-network.com", "sid": "seller_id1", "hp": 1 }, { "asi": "freewheel.tv", "sid": "486353", "hp": 1 } ], "ver": "1.0" } } Mandatory for ad servers who have clients that are declaring themselves as resellers/intermediaries. Please reference guidance from the IAB . 5.11 Regs Object Within the AdRequest Object, the Regs (Regulations) object contains any legal, governmental, or industry regulations that apply to the request. See Regs Object Example below Attribute Type Device Description Example Scope coppa integer app/web Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes. "coppa": 1 Recommended ext.us_privacy object.string app/web Communicates signals regarding consumer privacy under US privacy regulation. "ext": { "us_privacy": "1---" } Recommended ext.gpp object.string app/web Global Privacy Platform string See Regs Object Example below "ext": { "gpp": "DBABLA~BVQqAAAAAWA" } Optional ext.gpp_sid object.integer_array app/web Global Privacy Platform Section ID string See Regs Object Example below "ext": { "gpp_sid": [6, 8] } Optional ext.gdpr object.integer app/web Flag that indicates whether or not the request is subject to GDPR regulations. 0 = No, 1 = Yes, omission indicates unknown. "ext": { "gdpr": 1 } Recommended ext.dsa object app/web DSA transparency object. Please note that the client must work with their FreeWheel team to enable this on their network to adhere to dsa in bid requests/responses. Please reference the dsa transparency IAB specification for more information: https://github.com/InteractiveAdvertisingBureau/openrtb/blob/main/extensions/community_extensions/dsa_transparency.md "ext": { "dsa": { "dsarequired": 3, "pubrender": 0, "datatopub": 2, "transparency": [ { "domain": "platform1domain.com", "params" : [ 1 ] } ] } } Optional gdpr integer app/web Flag that indicates whether or not the request is subject to GDPR regulations. 0 = No, 1 = Yes, omission indicates unknown. "gdpr": 1 Recommended gpp string app/web Global Privacy Platform string "gpp": "DBABLA~BVQqAAAAAWA" Optional gpp_sid integer array app/web Global Privacy Platform Section ID string "gpp_sid": [6, 8] Optional 5.11.1 Regs Object Example "regs": { "coppa": 1, "ext": { "us_privacy": "1yn-", "gdpr": 0, "gpp": "DBACNYA~CPXxRfAPXxRfAAfKABENB-CgAAAAAAAAAAYgAAAAAAAA~1YNY", "gpp_sid": [6, 8] } } 5.12 Video Object Within the Imp object(s), the Video object represents an in-stream or outstream video impression. Video in OpenRTB generally assumes compliance with the VAST standard, and is a required object. oRTB 2.6 Dynamic Podding is supported, however, not all attributes are supported. See the table for what attributes are supported. Attribute Type Device Description Example Scope mimes string array app/web Supported content MIME types. "mimes": ["video/mp4"] Mandatory minduration integer app/web Minimum video ad duration in seconds "minduration": 12 Recommended maxduration integer app/web Maximum video ad duration in seconds. "maxduration": 3200 Recommended protocols integer array app/web Array of supported video protocols. "protocols": [ 3, 6, 2, 5 ] Recommended w integer app/web Width of the video player in device independent pixels (DIPS). "w": 1920 Recommended h integer app/web Height of the video player in device independent pixels (DIPS). "h": 1080 Recommended linearity integer app/web Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed. "linearity": 1 Recommended startdelay integer app/web Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. "startdelay": -1 Recommended (Mandatory if placement is not passed) minbitrate integer app/web Minimum bit rate in Kbps. "minbitrate": 300 Optional maxbitrate integer app/web Maximum bit rate in Kbps. "maxbitrate": 25000 Optional placement integer app/web 1 In-Stream, 2 In-Banner, 3 In-Article, 4 In-Feed, 5 Interstitial/Slider/Floating. "placement":1 Recommended (Mandatory if startdelay is not passed) plcmt integer app/web Updated video placement type signal. See IAB spec for more information on how this should be populated 1 Instream, 2 Accompanying Content, 3 Interstitial, 4 No Content/Standalone "plcmt":1 Recommended (Mandatory if startdelay is not passed) playbackmethod integer array app/web 1 autoplay with sound, 2 autoplay without sound, 3 click to play, 4 mouse over, 5 entering viewport sound on since openRTB 2.5, 6 entering viewport sound off since openRTB 2.5 "playbackmethod": [1, 3] Recommended api integer array app/web List of supported API frameworks for this impression. Refer to List: API Frameworks in AdCOM 1.0. If an API is not explicitly listed, it is assumed not to be supported. "api": [1, 2, 7] Optional maxseq integer app/web Indicates the maximum number of ads that may be served into a dynamic video ad pod "maxseq": 8 Optional (Mandatory if using dynamic ad podding) poddur integer app/web Indicates the total amount of time in seconds that advertisers may fill for a dynamic video ad pod "poddur": 145 Optional (Mandatory if using dynamic ad podding) 5.13 Geo Object Within the Device object, this object indicates the location of the device, which can also be interpreted as the user's current location. Attribute Type Device Description Example Scope country string app/web Country code using ISO-3166-1-alpha-3. "country": "FRA" Recommended lat float app/web Latitude from -90.0 to +90.0, where negative is south. "lat": 48.8566 Optional lon float app/web Longitude from -180.0 to +180.0, where negative is west. "lon": 2.35222 Optional zip string app/web Zip or postal code. "zip": "10001" Optional 5.14 Content Object Within the App or Site object, the content object describes the content in which the impression will appear, which may be direct or syndicated content. Attribute Type Device Description Example Scope cat string array app/web Array of IAB content categories that describe the content producer using IAB Categories v1.0 "cat": [ "IAB12" ] Recommended genre string app/web Genre that best describes the content (e.g., horror, comedy, etc). "genre": "comedy" Recommended language string app/web Content language using ISO-639-1-alpha-2. "language": "en" Recommended title string app/web Content title. "title": "Back to the Future" Recommended series string app/web Content series. series: "The Office" Recommended contentrating string app/web Content rating, e.g. MPAA rating "contentrating": "R" Recommended userrating string app/web User rating of the content (e.g., number of stars, likes, etc.). "userrating": "5" Recommended livestream integer app/web 0 = not live, 1 = content is live (e.g., stream, live blog). "livestream": 0 Recommended len integer app/web Length of video content in seconds "len": 7200 Recommended producer object app/web Content producer name "producer": { "name": "Warner Bros" } Recommended qagmediarating integer app/web Media rating per IQG guidelines. 1: All Audiences, 2: Everyone over 12, 3: Mature Audiences. "gamediarating": 1 Recommended channel object app/web Channel the content is on (e.g., a local channel like “WABC-TV") "channel": { "name": "The PGA TOUR Channel" } Recommended network object app/web Network the content is on (e.g., a TV network like “ABC") "network": { "name": "ABC" } Recommended prodq integer app/web Production quality. Refer to List: https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list_productionqualities "prodq": 1 Recommended keywords string app/web Comma separated list of keywords describing the content. "keywords": "NRS-TV,Entertainment" Optional ext.channel string app/web Channel the content is on (e.g., a local channel like “WABC-TV") "ext": { "channel": "The PGA TOUR Channel" } Optional content.ext.network string app/web Network the content is on (e.g., a TV network like “ABC") "ext" : { "network" : "NBCUniversal" } Optional 5.15 Ext Object Optional extensions and customized fields. These are also listed in their respective parent objects above. Attribute Type Device Description Example Parent Object(s) keywords object app/web See Keywords Object AdRequest custom_site_section_id string app/web You can pass the site section ID in the ext object within the imp object if it cannot be passed in the site or app object ID field. "custom_site_section_id" : "site_section_tag_xyz123" AdRequest,Imp (if present in both objects,AdRequest will take precedence) profile_id string app/web Indicate configurations such as creative restrictions and compliance related settings. Pass the profile name "profile_id": "123456:profile_name_xyz123" (Recommended) -or- "profile_id": "profile_name_xyz123" AdRequest,Imp (if present in both objects,AdRequest will take precedence) network_id string app/web Pass the Freewheel Network ID "network_id":"123456" AdRequest,Imp (if present in both objects,AdRequest will take precedence) fw_gd integer app/web Add this field with value set to 1 to indicate the inventory is guaranteed from ad-server side for demand guaranteed from Freewheel. When set to 1, Freewheel will only return guaranteed demand. Publishers should send a separate request without this flag in order to receive non-guaranteed demand. Any publisher passing this field with a value of 1 should first consult with Freewheel to ensure correct setup for guaranteed demand has been done " fw_gd ": 1 AdRequest, Imp (if present in both objects, ad request will take precedence) inventorypartnerdomain string app/web inventorypartnerdomain declaration for ads.txt "inventorypartnerdomain": "programmerA.com" Site, App lmt integer app/web ATTS and LAT values combined in single 0/1 value "lmt": 1 Device ifv string app/web Device identifier for vendors. "ifv": "336F2BC0-245B-4242-8029-83762AB47B15" Device atts integer app/web Indicates Apple’s App Tracking Authorization status. "atts": 1 Device ifa_type string app/web IAB Recommended values for ifa_type : dpid - the generic “device provided id”, but based on historical usage, common device type specific values can be used. rida - Roku id aaid - Android id idfa - Apple id afai - Amazon Fire id msai - Microsoft id ppid - publisher provided id sspid - SSP provided id sessionid - session id / synthetic id "ifa_type": "idfa" Device channel string app/web Channel the content is on (e.g., a local channel like “WABC-TV") "ext": { "channel": "The PGA TOUR Channel" } Content gdpr integer app/web Flag that indicates whether or not the request is subject to GDPR regulations. 0 = No, 1 = Yes, omission indicates unknown. "gdpr": 1 User, Regs(if present in both objects, Regs will take precedence) consent string app/web Encoded user consent string based on GDPR Consent Working Group structure "consent": "BOSSotLOSSotLAPABAENBc-AAAAgR7_______9______9uz_Gv_v_f__33e8__9v_l_7_-___u_-33d4-_1vX99yfm1-7ftr3tp_86ues2_XqK_9oIiA" User, Regs(if present in both objects, Regs will take precedence) schain object app/web Supply Chain information and an array of nodes. "schain": { "complete": 1, "nodes": [ { "asi": "ad-network.com", "sid": "seller_id1", "hp": 1 }, { "asi": "freewheel.tv", "sid": "486353", "hp": 1 } ], "ver": "1.0" } Source eids object app/web External IDs for syncing purposes. "eids": [{ "source": "id5 - sync.com", "uids": [{ "ext": { "linkType ": 1 }, "id": "hashed_id", "atype": 1 } ] }, { "source": "criteo.com", "uids": [{ "id ": "hashed_uid ", "atype": 1 } ] } ] User gpp string app/web Global Privacy Platform string "gpp": "DBABLA~BVQqAAAAAWA" Regs gpp_sid integer array app/web Global Privacy Platform Section ID string "gpp_sid": [6, 8] Regs us_privacy string app/web Communicates signals regarding consumer privacy under US privacy regulation. "us_privacy": "1yn-" Regs dsa object app/web DSA transparency object. Please note that the client must work with their FreeWheel team to enable this on their network to adhere to dsa in bid requests/responses. Please reference the dsa transparency IAB specification for more information: IAB specification "ext": { "dsa": { "dsarequired": 3, "pubrender": 0, "datatopub": 2, "transparency": [ { "domain": "platform1domain.com", "params" : [ 1 ] } ] } } Regs 5.16 Keywords Object Within the Extension object in the main AdRequest, this object can be used to pass through custom fields and additional value-enhancing information. It can also be used to pass through Freewheel-specific ad request key-values which can be found here Attribute Type Device Description Example Scope Custom Key-Value Pair string app/web Any custom fields that a publisher requires can be passed as a key-value pair in the keywords object. If a single key requires multiple values, those values can be passed in a list. See example. "keywords": { "age": "35-44", "gender": "male", "city": ["New York", "Chicago"] } Optional _fw_h_x_timezone string app/web User timezone "_fw_h_x_timezone": "-05:00" Optional _fw_cookie_consent string web 0: no consent, restrict cookie 1: consent obtained, don't restrict cookie "_fw_cookie_consent": "1" Recommended _fw_h_x_city string app/web City information - used as fallback if GDPR consent is not given "_fw_h_x_city": "phoenix" Optional _fw_h_x_dma string app/web DMA information - used as fallback if GDPR consent is not given "_fw_h_x_dma": "501" Optional _fw_h_x_state string app/web State information - used as fallback if GDPR consent is not given "_fw_h_x_state": "arizona" Optional _fw_content_programmer_brand string app/web Specifies Programmer Brand in the request. A Programmer Brand is a collection of channels from a single Programmer. Programmer Brand values are provided by video content owners. "_fw_content_programmer_brand": "brand-name" Optional _fw_content_genre string app/web Specifies genre of the content and will be detected by the FW ADS as a Standard Attributes. See the genre section in Publishers can coordinate with their Account Managers to discuss supported objects Alternative to content.genre. "_fw_content_genre":"genre1,genre2,..." Optional _fw_content_programmer_brand_channel string app/web Specifies channel that content is aired on. Channel attributes are a child of the Brand attributes, and can only be associated with one Brand attribute. Programmer Brand Channel values are provided by video content owners. "_fw_content_programmer_brand_channel": "channel_name" Optional _fw_content_language string app/web Specifies the language of content associated with Marketplace Platform inventory. Multiple languages can be applied to a Network Item, though a child item's language setting will take precedence. To ensure accurate classification during ad request evaluations, Network Items representing supply must be mapped with the correct language. Publishers can coordinate with their Account Managers to discuss supported objects "_fw_content_language": "language_name" Optional _fw_content_rating string app/web Specifies the content rating associated with inventory. This attribute can be applied to sell listings using the TV Content Rating attribute to ensure accurate classification. Publishers can coordinate with their Account Managers to discuss supported objects "_fw_content_rating": "TV-PG" Optional _fw_content_stream_mode string app/web Classifies inventory as either Live or On-Demand. Stream Type values can also be declared at both Level 1 and Level 2 on the Network Design to provide more accurate classification of the inventory. If not declared, Level 2 Stream Type will appear as "Unclassified" in reports. Publishers can coordinate with their Account Managers to discuss supported objects "_fw_content_stream_mode": "live" Optional _fw_platform string app/web Refers to the type of device that the request originates from. All device types are declarable by default or by the user agent. Publishers can coordinate with their Account Managers to discuss supported objects "_fw_platform": "device_type" Optional 5.17 Standard Attributes for Inventory Standardization Standard Attributes allow partner to curate and discover inventory with greater clarity and consistency. Beneficial to both buyers and sellers, standard attributes perform the following functions: Enhance clarity and discoverability: Sellers can standardize inventory by mapping standard attributes to Network Items in order to increase transparency for buyers in the Marketplace Platform. Standard attributes are organized into categories by content, platform and endpoint, geo location, and break and creatives. Improve targeting : Buyers can target standard attributes for inventory acquired through the Marketplace Platform. Increase the accuracy of reporting and forecasting projections. Standard Attributes in the oRTB-s requests can be passed in multiple locations, but the recommended location is in the ext.keywords object. More information on Standard Attributes can be found here . The Standard Attributes outlined in the list below appear in precedence order on how they are detected in the OpenRTB request: There are 18 additional Standard Attributes that are mandatory for standard attribute detection. A complete list of those can be found Inventory Standardization from OpenRTB-S Guide . 6. Response Fields 6.1 BidResponse Object Attribute Type Description Example id string Unique ID of the ad request to which this is a response. "id": "22945_1680294581308005-305_1" seatbid object array Array of seatbid objects see Seatbid object bidid string Bidder generated response ID to assist with logging/tracking. "bidid": "c3e048e2-d002-11ed-a24a-008902a05642" cur string Currency of the bid response. This is passed in the network currency "cur": "EUR" 6.2 Seatbid Object Attribute Type Description Example bid object array Array of 1 or more Bid objects each related to an impression. see Bid object seat string ID of the buyer seat on whose behalf this bid is made. By default, it is set to " FreeWheel " "seat": " FreeWheel " 6.3 Bid Object Attribute Type Description Example id string Unique ID of the bid "id": "c3e048e2-d002-11ed-a24a-008902a05642/1" impid string ID of the Imp object in the related ad request. "impid": "1" price float Bid price expressed as CPM although the actual transaction is for a unit impression only. "price": 26.002 adid string ID of a preloaded ad to be served if the bid wins. "adid": "255329" placementid string The placement ID of an ad in the Freewheel system "placementid": "12345" adm string Used for sending inline VAST/creative response and any tracking in bid response. "adm": " < inline_VAST> \n " adomain string array Advertiser domain for block list checking. "adomain": [" advertiserdomain.com "," advertiserdomain2.com "," advertiserdomain3.com "] cid string Campaign ID to assist with ad quality checking. "cid": "2730526348" crid string Creative ID to assist with ad quality checking. "crid": "2732710315" cat string array Array of IAB v1.0 Categories associated with the creative "cat": ["IAB1"] dur integer Duration of the creative in seconds "dur": 30 ext.dealid string Programmatic Module External Deal ID of the bid from the client's network. Please note that this field is used for reporting only and is not equivalent to the bid.dealid field in the OpenRTB specification. In cases where there is no Programmatic Module deal ID, either the Marketplace Sold Order ID will be returned or the below hardcoded values will return depending on the demand type: "freewheel-marketplace-exchange" "freewheel-open-exchange" This field is not enabled by default. Please reach out to your FreeWheel account team for enablement. "ext": { "dealid": "FRE-XYZ-123" } ext.dspid integer Numeric FreeWheel DSP ID for Programmatic Module demand. In cases where the DSP ID cannot be shared, this field will contain values: "-1" for Marketplace Platform Private "-2" for Marketplace Platform Exchange This field is not enabled by default. Please reach out to your FreeWheel account team for enablement. "ext": { "dspid": 123 } ext.dsa object DSA Ad Transparency information. Please note that the client must work with their FreeWheel team to enable this on their network to adhere to dsa in bid requests/responses. Please reference the dsa transparency IAB specification for more information: IAB specification "ext": { "dsa": { "behalf": "CompanyXYZ", "paid": "Sponsor ABC", "transparency": [ { "domain": "dsp1domain.com", "params": [ 1, 2 ] } ] "adrender": 1 } } 6.4 Ext Object Attribute Type Description Example Parent Object(s) dealid string Programmatic Module External Deal ID of the bid from the client's network. Please note that this field is used for reporting only and is not equivalent to the bid.dealid field in the OpenRTB specification. In cases where there is no Programmatic Module deal ID, either the Marketplace Sold Order ID will be returned or the below hardcoded values will return depending on the demand type: "freewheel-marketplace-exchange" "freewheel-open-exchange" This field is not enabled by default. Please reach out to your FreeWheel account team for enablement. "ext": { "dealid": "FRE-XYZ-123" } Bid dspid integer Numeric FreeWheel DSP ID for Programmatic Module demand. In cases where the DSP ID cannot be shared, this field will contain values: "-1" for Marketplace Platform Private "-2" for Marketplace Platform Exchange This field is not enabled by default. Please reach out to your FreeWheel account team for enablement. "ext": { "dspid": 123 } Bid dsa object DSA Ad Transparency information. Please note that the client must work with their FreeWheel team to enable this on their network to adhere to dsa in bid requests/responses. Please reference the dsa transparency IAB specification for more information: IAB specification "ext": { "dsa": { "behalf": "CompanyXYZ", "paid": "Sponsor ABC", "transparency": [ { "domain": "dsp1domain.com", "params": [ 1, 2 ] } ] "adrender": 1 } } Bid 7. Response Codes Response Code Meaning 200 Bid successful 400 Malformed json, or invalid Network ID, or invalid Profile ID 403 Network is not permissioned for ORTB-S, or app bundle/domain/ua are forbidden 204 No bid 5xx API Server-side error 8. Glossary Term Definition Dynamic Ad Podding Under the ORTB 2.6 specification, Dynamic Ad Podding offers a structure whereby an indeterminate number of ads can be requested to fill a known ad break duration Endpoint A digital location exposed via the API whereby requests can be sent and received Network Your publisher account at Freewheel. The linking of one or more Publishers to one or more Buyers under an agreed set of Rules, using OpenRTB. It is a safe and 100% controlled environment for the publisher to auction their video impressions. Each network has a unique identifier known as a Network ID Object JSON object literals, a.k.a JSON objects, are surrounded by curly braces {}. Keys and values are separated by a colon. Keys must be strings, and values must be a valid JSON data type: string number object array boolean null oRTB openRTB Profile A set of configurations that define which ads will be playable given the player environment and framework. This is set up in the backend during integration, and the correct profile for the player to set will be provided by FreeWheel. Site Section An Ad placement within a network VAST Video Ad Serving Template, developed by IAB as a framework to embed third-party video ads into a video stream: an XML markup schema placed on a publisher's website to display ads. 9. Sample Requests 9.1 App Request {
"id": "851011cf-06d2-4ba5-bb50-4bbc509490bc",
"cur": [
"USD"
],
"at": 1,
"bcat": [
"IAB23",
"IAB11"
],
"tmax": 600,
"app": {
"id": "APPLICATION ID OR REPLACED BY SITE SECTION ID OR CUSTOM SITE SECTION TAG",
"bundle": "com.app.name",
"cat": [
"IAB1",
"IAB2"
],
"name": "app-name",
"publisher": {
"id": "1234",
"name": "publisher-name"
},
"storeurl": "https://www.example.com/us/appstore/app/1234",
"ver": "1.0",
"ext": {
"inventorypartnerdomain": "example.com"
},
"content": {
"cat": [
"IAB2"
],
"contentrating": "tv-14",
"genre": "GV,Entertainment,Automotive,Talk Show",
"keywords": "NRS-TV,Entertainment",
"language": "en",
"len": 2700,
"livestream": 1,
"prodq": 1,
"qagmediarating": 1,
"series": "VOD",
"title": "WeatherNation Live",
"userrating": "4.6",
"producer": {
"name": "prorducer-name"
},
"network": {
"name": "network-name"
},
"channel": {
"name": "channel-name"
}
}
},
"device": {
"devicetype": 3,
"ext": {
"atts": 2,
"ifa_type": "dpid",
"ifv": "A994A398-3AD5-4296-8FFC-A97940C6BAA6",
"lmt": 0
},
"geo": {
"country": "USA",
"lat": 28.7115,
"lon": -81.5135,
"zip": "32712"
},
"ifa": "28febb41-2152-da34-f95a-bb0f89540e2c",
"ip": "192.168.0.1",
"ipv6": "::ffff:192.168.0.1",
"language": "en",
"lmt": 0,
"make": "Roku",
"model": "K000X",
"os": "Other",
"ua": "Roku/DVP-13.1 (13.1.4.1510-H2)"
},
"ext": {
"custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG",
"network_id": "REPLACED BY NETWORKID",
"profile_id": "REPLACED BY PROFILE NAME",
"fw_gd": 1,
"keywords": {
"_fw_content_programmer_brand": "brand-name",
"_fw_cookie_consent": "1",
"_fw_h_x_city": "city-name",
"_fw_h_x_dma": "501",
"_fw_h_x_state": "state-name",
"_fw_h_x_timezone": "-05:00"
}
},
"imp": [
{
"id": "1",
"secure": 1,
"bidfloor": 8.2018,
"bidfloorcur": "USD",
"ext": {
"custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG",
"fw_gd": 1,
"network_id": "REPLACED BY NETWORK ID",
"profile_id": "REPLACED BY PROFILE NAME"
},
"video": {
"api": [
1,
2,
7
],
"battr": [
1,
3,
5,
8,
9
],
"h": 1080,
"linearity": 1,
"maxbitrate": 30000,
"maxduration": 30,
"mimes": [
"video/mp4",
"video/H264"
],
"minbitrate": 240,
"minduration": 6,
"placement": 1,
"playbackend": 1,
"playbackmethod": [
1
],
"plcmt": 1,
"protocols": [
1,
2,
3,
4,
5,
6,
7,
8
],
"startdelay": 0,
"w": 1920
}
}
],
"regs": {
"coppa": 0,
"ext": {
"consent": "",
"gdpr": 0,
"gpp": "DBABLA~BVQqAAAAAWA",
"gpp_sid": [
7
],
"us_privacy": "1---"
},
"gdpr": 0,
"gpp": "DBABLA~BVQqAAAAAWA",
"gpp_sid": [
7
]
},
"source": {
"ext": {
"schain": {
"complete": 1,
"nodes": [
{
"asi": "lkqd.net",
"hp": 1,
"sid": "1100053830"
},
{
"asi": "krushmedia.com",
"hp": 1,
"rid": "b6d8343b-8413-ee6d-1c36-8152f30ef8f7",
"sid": "AJxF6R43a9M6CaTvK"
}
],
"ver": "1.0"
}
}
},
"user": {
"buyeruid": "eaa46e6cc2b0d66a59f41667b264fefb",
"ext": {
"consent": "BOSSotLOSSotLAPABAENBc-AAAAgR7_______9______9uz_Gv_v_f__33e8__9v_l_7_-___u_-33d4-_1vX99yfm1-7ftr3tp_86ues2_XqK_9oIiA",
"eids": [
{
"source": "pubcid.org",
"uids": [
{
"id": "8309ad21-b466-4cc9-8287-8354bd442dd6"
}
]
}
],
"gdpr": 0
},
"id": "RX-817f6b9c-b8f5-45fd-9ed6-3544206b4055-005"
}
} 9.2 Site Request {
"id": "b6d8343b-8413-ee6d-1c36-8152f30ef8f7",
"cur": [
"USD"
],
"at": 1,
"bcat": [
"IAB23",
"IAB11"
],
"tmax": 600,
"site": {
"id": "SITE ID OR REPLACED BY SITE SECTION ID OR CUSTOM SITE SECTION TAG",
"cat": [
"IAB12"
],
"domain": "example.com",
"ext": {
"inventorypartnerdomain": "example.com"
},
"name": "site-name",
"page": "https://example.com/article/1234",
"publisher": {
"id": "1234",
"name": "publisher-name"
},
"ref": "https://exmaple.com/",
"content": {
"cat": [
"IAB2"
],
"contentrating": "tv-14",
"genre": "GV,Entertainment,Automotive,Talk Show",
"keywords": "NRS-TV,Entertainment",
"language": "en",
"len": 2700,
"livestream": 1,
"prodq": 1,
"qagmediarating": 1,
"series": "VOD",
"title": "WeatherNation Live",
"userrating": "4.6",
"producer": {
"name": "prorducer-name"
},
"network": {
"name": "network-name"
},
"channel": {
"name": "channel-name"
}
}
},
"device": {
"devicetype": 1,
"ext": {
"atts": 2,
"ifa_type": "dpid",
"ifv": "A994A398-3AD5-4296-8FFC-A97940C6BAA6",
"lmt": 0
},
"geo": {
"country": "USA",
"lat": 28.7115,
"lon": -81.5135,
"zip": "32712"
},
"ifa": "28febb41-2152-da34-f95a-bb0f89540e2c",
"ip": "192.168.0.1",
"ipv6": "::ffff:192.168.0.1",
"language": "en",
"lmt": 0,
"make": "Generic",
"model": "Android 6.0",
"os": "Android",
"ua": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Mobile Safari/537.36"
},
"ext": {
"custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG",
"network_id": "REPLACED BY NETWORK ID",
"profile_id": "REPLACED BY PROFILE NAME",
"fw_gd": 1,
"keywords": {
"_fw_content_programmer_brand": "brand-name",
"_fw_cookie_consent": "1",
"_fw_h_x_city": "city-name",
"_fw_h_x_dma": "501",
"_fw_h_x_state": "state-name",
"_fw_h_x_timezone": "-05:00"
}
},
"imp": [
{
"id": "1",
"secure": 1,
"bidfloor": 8.2018,
"bidfloorcur": "USD",
"ext": {
"custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG",
"network_id": "REPLACED BY NETWORK ID",
"profile_id": "REPLACED BY PROFILE NAME",
"fw_gd": 1
},
"video": {
"api": [
1,
2,
7
],
"battr": [
1,
3,
5,
8,
9
],
"h": 1080,
"linearity": 1,
"maxbitrate": 30000,
"maxduration": 30,
"mimes": [
"video/mp4",
"video/H264"
],
"minbitrate": 240,
"minduration": 6,
"placement": 1,
"playbackend": 1,
"playbackmethod": [
1
],
"plcmt": 1,
"protocols": [
1,
2,
3,
4,
5,
6,
7,
8
],
"startdelay": 0,
"w": 1920
}
}
],
"regs": {
"coppa": 0,
"ext": {
"consent": "",
"gdpr": 0,
"gpp": "DBABLA~BVQqAAAAAWA",
"gpp_sid": [
7
],
"us_privacy": "1---"
},
"gdpr": 0,
"gpp": "DBABLA~BVQqAAAAAWA",
"gpp_sid": [
7
]
},
"source": {
"ext": {
"schain": {
"complete": 1,
"nodes": [
{
"asi": "lkqd.net",
"hp": 1,
"sid": "1100053830"
},
{
"asi": "krushmedia.com",
"hp": 1,
"rid": "b6d8343b-8413-ee6d-1c36-8152f30ef8f7",
"sid": "AJxF6R43a9M6CaTvK"
}
],
"ver": "1.0"
}
}
},
"user": {
"buyeruid": "eaa46e6cc2b0d66a59f41667b264fefb",
"ext": {
"consent": "",
"eids": [
{
"source": "pubcid.org",
"uids": [
{
"id": "8309ad21-b466-4cc9-8287-8354bd442dd6"
}
]
}
],
"gdpr": 0
},
"id": "RX-817f6b9c-b8f5-45fd-9ed6-3544206b4055-005"
}
} 9.3 Dynamic Podded Request {
"app": {
"bundle": "com.app.name",
"content": {
"cat": [
"IAB12"
],
"channel": {
"name": "channel-name"
},
"contentrating": "TV-G",
"context": 1,
"ext": {
"inventorypartnerdomain": "example.com"
},
"genre": "Bulletin",
"id": "aageykaagenda",
"keywords": "ABP News",
"language": "en",
"livestream": 0,
"network": {
"name": "network-name"
},
"series": "Aagey ka Agenda",
"title": "Aagey ka Agenda"
},
"id": "APPLICATION ID OR REPLACED BY SITE SECTION ID OR CUSTOM SITE SECTION TAG",
"name": "app-name",
"storeurl": "https://www.example.com/us/appstore/app/1234"
},
"at": 1,
"device": {
"devicetype": 3,
"ext": {
"ifa_type": "aaid"
},
"geo": {
"city": "Gurugram",
"country": "IN",
"lat": 28.4597,
"lon": 77.0282,
"metro": "0",
"region": "HR",
"zip": "122001"
},
"ifa": "7fb4c359-9912-4b16-9960-33cd7cbc2a18",
"ip": "192.168.0.1",
"lmt": 0,
"make": "Xiaomi",
"model": "MiTV-AXSO2",
"os": "Android",
"osv": "11",
"ua": "Dalvik/2.1.0 (Linux; U; Android 11; MiTV-AXSO2 Build/RTT0.211201.001)"
},
"ext": {
"custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG",
"fw_gd": 1,
"keywords": {
"_fw_content_programmer_brand": "brand-name",
"_fw_cookie_consent": "1",
"_fw_h_x_city": "city-name",
"_fw_h_x_dma": "501",
"_fw_h_x_state": "state-name",
"_fw_h_x_timezone": "-05:00"
},
"network_id": "REPLACED BY NETWORKID",
"profile_id": "REPLACED BY PROFILE NAME"
},
"id": "ct8jj1ri38r1hgri9u4g",
"imp": [
{
"bidfloor": 0.5,
"ext": {
"custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG",
"fw_gd": 1,
"network_id": "REPLACED BY NETWORK ID",
"profile_id": "REPLACED BY PROFILE NAME"
},
"id": "556650_ct8jj1ri38r1hgri9u2g_1",
"secure": 1,
"video": {
"delivery": [
1,
2
],
"h": 1080,
"linearity": 1,
"maxbitrate": 30000,
"maxduration": 120,
"mimes": [
"video/mp4",
"video/H264"
],
"minbitrate": 240,
"minduration": 6,
"placement": 1,
"playbackmethod": [
1
],
"plcmt": 1,
"maxseq": 4,
"poddur": 60,
"podid": "1",
"protocols": [
1,
2,
3,
4,
5,
6,
7,
8
],
"w": 1920
}
}
],
"regs": {
"ext": {
"gdpr": 0,
"us_privacy": "1---"
}
},
"source": {
"ext": {
"schain": {
"complete": 1,
"nodes": [
{
"asi": "lkqd.net",
"hp": 1,
"sid": "1100053830"
},
{
"asi": "krushmedia.com",
"hp": 1,
"rid": "b6d8343b-8413-ee6d-1c36-8152f30ef8f7",
"sid": "AJxF6R43a9M6CaTvK"
}
],
"ver": "1.0"
}
}
},
"tmax": 850,
"user": {
"ext": {
"consent": "CP0QLgAP0QLgAAGABCENDbCgAAAAAEPAABBoAAARvgFgAVABIADQAJgAUgD_gIWAYyAyMB7QEbwBwoAMAKQCFgGMigAYATAD_gMjGAAgAmAMjHgAwApAIWAYyQABABMAZGTABABSAYyVAAgMZAAA.YAAAAAAAAAAA",
"us_privacy": "1---"
}
}
} 10. Sample Responses 10.1 App Response {
"id": "request-id",
"bidid": "internal-id",
"cur": "USD",
"seatbid": [
{
"bid": [
{
"adid": "1234",
"adm": "...",
"adomain": [
"example.com"
],
"cat": [
"IAB2"
],
"cid": "0",
"crid": "4:example.com/1234",
"dur": 30,
"id": "1",
"impid": "1",
"price": 10
}
],
"seat": "FreeWheel"
}
]
} 10.2 Dynamic Pod Response {
"bidid": "25538_1559714932183049-244_1",
"cur": "EUR",
"id": "25538_1559714932183049-244_1",
"seatbid": [
{
"bid": [
{
"adid": "723012",
"adm": "...",
"adomain": [
"StickyAds.com"
],
"cid": "0",
"crid": "2:072d87f9f9ac654758112d62eeee0d8b7160606694818028045",
"dur": 10,
"id": "1",
"impid": "1",
"price": 27.522
},
{
"adid": "733012",
"adm": "....",
"adomain": [
"StickyAds.com"
],
"cid": "0",
"crid": "3:54ed7ea4060b7bc2b9d7c7bf4e603d5316489806525904299806",
"dur": 16,
"id": "2",
"impid": "1",
"price": 9.183174
},
{
"adid": "713012",
"adm": "...",
"adomain": [
"StickyAds.com"
],
"cid": "0",
"crid": "1:aa2ebc0fc2c33e7760c2196d0dd35fc413823698032879037899",
"dur": 30,
"id": "3",
"impid": "1",
"price": 27.522
}
],
"seat": "FreeWheel"
}
]
}