Link Search Menu Expand Document

PDF

BidRequest Object

Demand Partners

Last updated on August 10, 2020


When appropriate, Ad Exchange sends a BidRequest object to the URL specified for your account’s Real-time Bid URL setting. Each Ad Exchange bid request contains a BidRequest object, a single Imp object, and may include other objects to provide additional information about the impression.

The following diagram depicts a high-level view of the structure of each bid request.

NOTE

OpenX supports only one Imp object per BidRequest.

Some fields in each BidRequest must always be sent and others are optional. The BidRequest object includes the following fields:

Field nameData typeDescriptionSent?
idstringA unique ID for the request, which OpenX Ad Exchange uses to identify the auction.
For example, 888b4a7a-d259-11e0-9912-000c29b0c11a
If the ad request includes multiple ad sizes, you see multiple bid requests with the same ID. However, they represent one bid request that allows buyers to bid on different sizes.
Always
imparray (imp object)An object containing properties that describe the ad impression for which OpenX Ad Exchange is soliciting bids.
OpenX supports only one impression per bid request, which is expressed as an array with a single Imp object. This is because OpenX handles each ad unit as a separate ad request.
Always
sitesite objectAn object containing properties that describe the website where the ad is display if the bid request is for an impression on a website. The bid request can only have a Site or an App object.Sometimes
appapp objectAn object containing properties that describe the app where the ad is display if the bid request is for an impression within a mobile app. A bid request can only have an App or a Site object.Sometimes
devicedevice objectAn object containing properties that describe the device through which the impression is viewed, such as on a specific type of mobile phone.Sometimes
useruser objectAn object containing properties that describe the user viewing the impression.Sometimes
test (new)integerIndicates test mode (1), which is not billable. The default is 0, which indicates that the auction is billable.Sometimes
atintegerAuction type of the request.
   • 1 = First-price auction.
   • 2 = Second-price auction.
Always
curarray (string)A single-element array containing the ISO-4217 code for the currency in which OpenX expects bids, based on the currency configured in your account.Always
bcatarray (string)The list of advertiser categories that the publisher wants to block for the ad request. The BidRequest.bcat field supports the IAB categories listed in the IAB’s OpenRTB 2.5 specification, as well as the OX- prefix.

For example, "bcat": [ "IAB17-18", "IAB24", "IAB25", "IAB25-3", ],

The bcat field also supports OpenX categories, listed below, as well as OpenX category values without the OX- prefix. For example, both OX-1 and 1 values can be sent in this field. A request may contain a combination of IAB categories as well as OpenX categories. We recommend that buyers integrate to ingest values with the IAB categories as specified in the IAB’s OpenRTB 2.5 specification, as well as the OX- prefix.

OX-1. Adult
OX-2. Arts and Entertainment
OX-3. Automotive
OX-4. Business
OX-5. Careers
OX-6. Shopping
OX-7. Electronics
OX-8. Social Networking
OX-9. Family and Parenting
OX-10. Firearms and Weapons
OX-11. Food and Drink
OX-12. Gambling
OX-13. Government, Law and Politics
OX-14. Health and Fitness
OX-15. Hobbies and Interests
OX-16. Pets
OX-17. Home and Garden
OX-18. Technology and Computing
OX-19. Internet
OX-20. Mobile Websites and Apps
OX-21. News
OX-22. Real Estate
OX-23. Education
OX-24. Science
OX-25. Sports
OX-26. Tobacco and Smoking
OX-28. Travel
OX-29. Reference and Directory
OX-30. Personal Finance
OX-31. Telecommunications
OX-32. Social Science
OX-33. Style and Fashion
OX-34. Religion and Spirituality
OX-35. Society
OX-99. Not Classified
Sometimes
badvarray (string)Blocked advertiser, the list of top-level advertiser domains (for example, blockeddomain.com) blocked for this publisher as derived from the click URL. Domains are not case-sensitive.

Note: While OpenX does not currently pass this field, we are in the process of building out support for it. We recommend that you build support for it as part of your integration.
Sometimes
sourcesource objectAn object that provides data about the inventory source and which entity makes the final decision.Always (when enabled)
regsregs objectAn object containing properties that describe any regulations applicable to the request.Sometimes
extextensions objectAn object containing custom fields that describe the BidRequest.Sometimes

For additional publisher enrichment fields, see Supplemental Data.


Extensions Object

BidRequest.ext

The Extensions object and its ThirdPartyKeyValue object provide additional details about the BidRequest.

Field nameData typeDescriptionSent?
tp_key_valThirdPartyKeyValueAn object containing a list of third-party key-value pairs.Sometimes

ThirdPartyKeyValue Object

BidRequest.ext.tp_key_val

Field nameData typeDescriptionSent?
keystringThe third-party identifier key.Sometimes
valuestringThe value for the associated key.Sometimes

Source Object

Last updated on June 9, 2020

BidRequest.source


This object describes the nature and behavior of the entity that is the source of the bid request upstream from the OpenX Ad Exchange. The primary purpose of this object is to define post-auction or upstream decisioning when the OpenX Ad Exchange itself does not control the final decision. A common example of this is header bidding.

To enable this object or receive more information, please contact your Business Development Manager.

Field nameData typeDescriptionSent?
fdintegerEntity responsible for the final impression sale decision.
   • 0 = OpenX Ad Exchange.
   • 1 = Upstream source. For example: header bidding.
Always
tidstringTransaction ID that is common across all participants in this bid request (for example, potentially multiple exchanges).Sometimes
pchainstringPayment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0.Always
extextensions objectAn object containing properties that describe custom fields for the bid request source.Always

Extensions object

BidRequest.source.ext

The optional Extensions object can provide additional details about the source of the bid request.

Field nameData typeDescriptionSent?
schainstringRepresents both the links in the supply chain as well as an indicator whether or not the supply chain is complete.Sometimes

SupplyChain object

BidRequest.source.ext.schain

The SupplyChain object enables buyers to see all parties who are selling or reselling a given bid request. If you would like to receive schain in your bid requests from OpenX, please contact your Platform Development Manager. For more information please see the official IAB spec.

To interpret the OpenX node of the schain object, you can reference OpenX’s sellers.json file that contains a list of all our supply partners at openx.com/sellers.json. To interpret the node of any other advertising system in the schain, simply append “/sellers.json” to the provided asi.

Field nameData typeDescriptionSent?
completeintegerFlag indicating whether the chain contains all nodes leading back to the source of the inventory, where 0 = no, 1 = yes.Always
nodesobject arrayArray of SupplyChainNode objects in the order of the chain. In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction (for example, the owner of the site, app, or other medium). In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request.Always

SupplyChainNode object

BidRequest.source.ext.schain.node

Field nameData typeDescriptionSent?
asistringThe canonical domain name of the SSP, exchange, header wrapper, etc., system that bidders connect to. This may be the operational domain of the system, if that is different than the parent corporate domain, to facilitate WHOIS and reverse IP lookups to establish clear ownership of the delegate system. This should be the same value as used to identify sellers in an ads.txt file if one exists.Always
sidstringThe identifier associated with the seller or reseller account within the advertising system. This must contain the same value used in transactions (OpenRTB bid requests) in the field specified by the SSP/exchange. Typically, in OpenRTB, this is publisher.id. For OpenDirect it is typically the publisher’s organization ID. Should be limited to 64 characters in length.Always
ridstringThe OpenRTB RequestId of the request as issued by this seller.Sometimes
hpintegerIndicates whether this node is involved in the flow of payment for the inventory.
   • When set to 1, the advertising system in the asi field pays the seller in the sid field, who is responsible for paying the previous node in the chain.
   • When set to 0, this node is not involved in the flow of payment for the inventory.

For version 1.0 of SupplyChain, this property should always be 1. It is explicitly required to be included as it is expected that future versions of the specification introduces non-payment handling nodes. Implementers should ensure that they support this field and propagate it onwards when constructing SupplyChain objects in bid requests sent to a downstream advertising system.
Always

Imp Object

Last updated on September 10, 2018

BidRequest.imp


Each BidRequest object contains an array with a single Imp object to describe the impression. Each Imp object can contain one of the following objects to describe the ad space:

In addition, the Imp object can contain a Pmp object along with a Banner or Native object.

Field nameData typeDescriptionSent?
idstringA unique ID for the impression. For example, 1.
Note that the IAB’s OpenRTB 2.5 specification requires that you use the value of BidRequest.imp.id to populate BidResponse.seatbid.bid.impid.
Always
metricobject arrayAn array of Metric that offers insight into different metrics about the impression itself to assist with your bidding decisions.

A Metric object is always sent when it is enabled.
Sometimes
bannerbanner objectAn object containing properties that describe the display banner ad unit for this impression opportunity. A Banner object is always sent for banner impression opportunities.Sometimes
videovideo objectAn object containing properties that describe the display video ad unit for this impression opportunity. A Video object is always sent for video impression opportunities.Sometimes
nativenative objectAn object containing properties that describe a native ad impression opportunity. A Native object is always sent for native ad impression opportunities.Sometimes
pmppmp objectAn object containing properties that describe deals eligible for impressions. A pmp object is always sent for private marketplace deals.Sometimes
displaymanagerstringName of SDK technology or player responsible for rendering an ad (typically video or mobile).Sometimes
displaymanagerverstringVersion of SDK technology or player responsible for rendering an ad (typically video or mobile).Sometimes
instlintegerIndicates whether the request is for an interstitial ad (1) or not (0).Sometimes
secureintegerIf this impression must be SSL secured, all creative assets that are returned must use the HTTPS protocol, not HTTP.
   • 0 = False
   • 1 = True (HTTPS URLs are required.)
Sometimes
expintegerAdvisory as to the number of seconds that may elapse between the auction and the actual impression.Sometimes

For additional publisher enrichment fields, see Supplemental Data.


Metric Object

Last updated on May 18, 2018

BidRequest.imp.metric


This object is associated with an impression as an array of metrics. These metrics can offer insight into the impression to assist with decisioning (such as viewability). Each metric is identified by its type, reports the value of the metric, and optionally identifies the source or vendor measuring the value.

To enable this object or receive more information, please contact your Platform Development Manager.

Field nameData typeDescriptionSent?
typestringType of metric being presented (such as viewability). Please see the table below for a list of metric types supported by OpenX.Always
valuefloatNumber representing the value of the metric. Probabilities must be in the range 0.00 - 1.00Always
vendorstringSource of the value.Always

Supported metrics

The following is subject to regular updates. We strongly recommend regularly checking this table for new metrics that are supported by OpenX.

MetricTypeRange for valuePossible vendor values
Viewability score of the bid requestviewability0.00 - 1.00Moat, Active View

Last updated on September 27, 2018

BidRequest.imp.banner


Each Imp object can contain one Banner object, which is required for banner impressions.

Field nameData typeDescriptionSent?
wintegerThe width of the ad space, in pixels, where the ad of the winning bidder is displayed. For example, 300Sometimes
hintegerThe height of the ad space in pixels. For example, 250Sometimes
formatarray of format objectsArray of format objects representing the banner sizes permitted.Always
btypearray (integer)Blocked banner ad types.Sometimes
battrarray (integer)An array of blocked creative attributes. If no value is specified, all types are allowed. For a list of creative attribute values, see .Sometimes
apiarray (integer)One of the supported API standards or frameworks:
   • 2 = VPAID 2.0
   • 3 = MRAID 1.0
   • 4 = ORMMA
   • 5 = MRAID 2.0
For example, 2
Sometimes
extextensions objectAn object containing properties that describe custom fields related to this banner ad.Sometimes

For additional details, see the IAB’s OpenRTB 2.5 specification.

For additional publisher enrichment fields, see Supplemental Data.


Extensions object

BidRequest.imp.banner.ext

The optional Extensions object can provide the following details about the banner.

Field nameData typeDescriptionSent?
matching_ad_idarray (MatchingAdId object)A list of objects containing properties that describe matching ads for which OpenX Ad Exchange is soliciting bids from the bidder.Always

MatchingAdId object

BidRequest.imp.banner.ext.matching_ad_id

Each MatchingAdId object provides details about a matching ad for which OpenX Ad Exchange is soliciting bids.

Field nameData typeDescriptionSent?
ad_heightintegerThe height of the ad unit in which the ad is displayed. For example, 250Always
ad_widthintegerThe width of the ad unit in which the ad is displayed. For example, 300Always
campaign_idintegerThe ID for the business unit to which the matching ad belongs.Always
creative_idintegerThe ID for the matching ad.Always
placement_idintegerThe ID for the traffic set to which the matching ad belongs.Always

Video Object

Last updated on September 27, 2018

BidRequest.imp.video


The Video object provides details about a video ad request. Each Imp object can contain one Video object, which is required for video impressions. Alternatively, an Imp object can contain a Banner or a Native object.

See also, Video Examples.


Guidance on Video creatives

  • Suggested maximum file size: 10MB.
  • Preferred video file formats: MP4 (H.264) and JavaScript VPAID.
  • Accepted video file formats: HTML5, at least one media provided must be in MP4 format.
  • Dimensions: Video ads can be rendered in any size video player. For example, 480x360, 640x360, 1920x800.
  • Video bitrate: 240kbps - 4mbps, depending on device; at least one media at 1mbps or below is required.
  • Max frame rate: 30FPS.
  • Playback methods: All playback methods defined in OpenRTB are supported.
  • Video types:
    • In-stream (an ad that appears within video content, and can be pre, mid, or post-roll)
    • Out-stream
    • Interstitial: for mobile app video and opt-in video, video type is interstitial.
NOTE

Flash support deprecation: July 3, 2017. Deprecation includes the VPAID 1.0 API Framework and the following MIME types: application/x-shockwave-flash and video/x-flv.

Field nameData typeDescriptionSent?
mimesarray (string)An array of supported MIME types for content video. Below are just a few examples for app, though MIME types are also sent for web ads.
Android:
   • video/3gpp
   • video/mp4

iOS:
   • video/3gpp
   • video/mov
   • video/mp4
   • video/mpv
Always
mindurationintegerMinimum video ad duration (in seconds).Sometimes
maxdurationintegerMaximum video ad duration (in seconds).Sometimes
protocolsarray (integer)A list of supported video bid response protocols. OpenX supports the following values:
   • 2 = VAST 2.0
   • 3 = VAST 3.0
   • 5 = VAST 2.0 Wrapper
   • 6 = VAST 3.0 Wrapper
Always
wintegerWidth of the player (in pixels).Always
hintegerHeight of the player (in pixels).Always
startdelayintegerThe start delay (in seconds) for mid-roll ad placements, or an indication of the ad’s position within linear video content.
If the startdelay value is greater than 0, the position is mid-roll, and the value indicates the start delay. Possible values include:
   • > 0 = Mid-roll (value indicates start delay in seconds)
   • 0 = Pre-roll
   • -1 = Generic mid-roll
   • -2 = Generic post-roll
Always
placementintegerPlacement type for the impression. Possible values include:
   • 1 = In-Stream
   • 2 = In-Banner. OpenX does not support and, therefore, does not monetize, low-value video ad units, including in-banner video.
   • 3 = In-Article (out-stream)
   • 4 = In-Feed
   • 5 = Interstitial/Slider/Floating

Note: You can distinguish a full-screen interstitial (for example, in mobile) from a floating/slider unit via the imp.instl field.
Sometimes
linearityintegerIndicates whether the ad impression is linear or non-linear. OpenX currently supports a value of 1 (linear).Always
skipintegerAlways sent for opt-in video (rewarded video). Indicates if the player allows the video to be skipped, where:
   • 0 = No
   • 1 = Yes
For opt-in video, OpenX always passes 0.
Sometimes
battrarray (integer)An array of blocked creative attributes. If no value is specified, all types are allowed.Sometimes
maxextendedintegerIndicates whether extended video ad duration is allowed beyond the value of maxduration:
   • -1 = Extension is allowed and there is no limit
   • 0 = Extension is not allowed
   • >0 = Extension is allowed and the value indicates the number of seconds of extended play
Sometimes
minbitrateintegerThe minimum bitrate (in Kbps).Sometimes
maxbitrateintegerThe maximum bitrate (in Kbps).Sometimes
boxingallowedintegerIndicates whether letterboxing of 4:3 video content in a 16:9 window is allowed (1) or not (0). The default value is 1.Sometimes
playbackmethodarray (integer)Playback methods that may be in use. Only one method is typically used in practice. If none are specified, any method may be used.Sometimes
deliveryarray (integer)A list of supported delivery methods. For example, 1 for streaming or 2 for progressive. If no values are specified, assume all delivery methods are supported.Always
apiarray (integer)One of the supported API standards or frameworks:
   • 2 = VPAID 2.0
   • 3 = MRAID 1.0
   • 4 = ORMMA
   • 5 = MRAID 2.0
For example: 2
Sometimes
extobjectAn object containing properties that describe custom fields for the Video object.Always

For additional details, see the IAB’s OpenRTB 2.5 specification.

For additional publisher enrichment fields, see Supplemental Data.


Extensions object

BidRequest.imp.video.ext

Provides additional details about the video ad. The Video object may include an Extensions object.

Field nameData typeDescriptionSent?
matching_ad_idarray (MatchingAdId object)A list of objects containing properties that describe ads for which Ad Exchange is soliciting bids from the bidder.Always
skipintegerPresent only when inventory is opt-in video (rewarded video). Always set to 0 to identify non-skippable opt-in video.Sometimes
videotypestringPresent only when inventory is opt-in video. Always set to rewarded to identify non-skippable opt-in video.Sometimes

BidRequest.imp.video.ext.matching_ad_id

Each MatchingAdId object provides details about a matching ad for which Ad Exchange is soliciting bids.

Field nameData typeDescriptionSent?
ad_heightintegerThe height of the ad unit in which the ad is displayed. For example, 250
This field duplicates the h field described in the Video object.
Always
ad_widthintegerThe width of the ad unit in which the ad is displayed.
For example, 300
This field duplicates the w field described in the Video object.
Always
campaign_idintegerThe ID for the business unit to which the matching ad belongs.Always
creative_idintegerThe ID for the matching ad.Always
placement_idintegerThe ID for the traffic set to which the matching ad belongs.Always

Native Object

Last updated on January 30, 2018

BidRequest.imp.native


The Native object provides details about a native ad request. A well-structured response must comply with the OpenRTB dynamic native ads API specification.

Each Imp object can contain one Native object, which is required for native impressions. Alternatively, an Imp object can contain a Banner object.

Before the implementation of the OpenRTB native ads API, OpenX used key value pairs to describe a native ad opportunity. OpenX now passes a serialized string of structured JSON data describing the opportunity via the BidRequest.imp.native.request field. To respond to this opportunity, send your native markup via the BidResponse.seatbid.bid.adm field.

NOTE

Native ads are currently not available in the OpenX Ad Exchange.

Field nameData typeDescriptionSent?
apiarray (integer)One of the supported API standards or frameworks:
   • 2 = VPAID 2.0
   • 3 = MRAID 1.0
   • 4 = ORMMA
   • 5 = MRAID 2.0
For example, 2.
Sometimes
battrarray (integer)An array of blocked creative attributes. If no value is specified, all types are allowed. For a list of creative attribute values, see the IAB’s OpenRTB 2.5 specification.Sometimes
requeststringRequest markup complying with the OpenRTB dynamic native ads API specification (for example, a string of JSON data describing the native ad opportunity).
To respond to the native opportunity, include a serialized string of native markup in the BidResponse.seatbid.bid.adm field.
Always
verstringThe version of the native ads API specification. For example, 1Sometimes

For additional details, see the IAB’s:


Format Object

Last updated on February 27, 2017

BidRequest.imp.banner.format


This object represents an allowed size (specifically, height and width combination) for a banner impression. These are typically used as an array of objects for an impression where multiple sizes are permitted. It is recommended to submit multiple bids in a single BidResponse if you want to take advantage of the format object for multiple ad sizes.

To enable this object, or for more information about how to use the format object, please contact your Platform Development Manager.

Field nameData typeDescriptionSent?
wintegerWidth in device-independent pixels.Always
hintegerHeight in device-independent pixels.Always

Format object example

"banner": {
            "format": [
                {"w": 728, "h": 90},
                {"w": 320, "h": 50},
                {"w": 160, "h": 60}
              ],
          }    

Site Object

Last updated on April 18, 2017

BidRequest.site


If the available impression is on a website, Ad Exchange may include a Site object to describe the website.

A BidRequest can only contain a single Site or App object, not both.

A Site object can reference the Publisher object and the Content object.

Field nameData typeDescriptionSent?
catarray (string)The list of IAB content categories that apply to the site.Sometimes
domainstringThe site domain (for example, mywebsite.com), which maps to the domain of the bid request URL.Sometimes
extextensions objectAn object containing properties that describe custom fields related to this site.Sometimes
idstringThe ID for the site associated with this inventory purchase.Sometimes
mobileintegerIndicates whether the site has been programmed to optimize layout when viewed on mobile devices.
   • 0 = False
   • 1 = True (The site uses responsive web design.)
Sometimes
pagestringThe URL of the webpage where the impression will display.Sometimes
publisherpublisher objectAn object containing properties that describe the publisher of the Site or App for this impression opportunity.Sometimes
refstringThe referrer URL that navigated the end-user to the current page.Sometimes

For additional details, see:


App Object

Last updated on September 11, 2017

BidRequest.app


If the available impression is within a mobile app, the BidRequest includes the App object to describe the mobile app.

A BidRequest can only contain a single App or Site object, not both.

An App object can reference the Content object.

Field nameData typeDescriptionSent?
idstringThe OpenX-specific ID for the app associated with this inventory purchase.Sometimes
namestringThe name of the app.Sometimes
bundlestringThe unique ID of the app’s package (Android), bundle (iOS), or its AppStore ID.
For example, com.demo.openx or 123456789
Sometimes
domainstringThe domain of the app.
For example, mygame.foo.com
Sometimes
storeurlstringThe app store URL for this app.Sometimes
catarray (string)The list of IAB content categories for the app, as defined in the IAB’s OpenRTB 2.5 specification.Sometimes
publisherpublisher objectAn object containing properties that describe the publisher of the app.Sometimes

For additional details, see IAB’s OpenRTB 2.5 specification.

BidRequest.app.ext


Field nameData typeDescriptionSent?
alt_idstringThe numeric App Store ID for iOS app traffic.Always (if iOS)

For additional publisher enrichment fields, see Supplemental Data.


Publisher Object

Last updated on January 31, 2018

BidRequest.app.publisher or BidRequest.site.publisher


The Publisher object describes the seller of the ad space (for the App or Site) in which the ad is displayed.

Field nameData typeDescriptionSent?
idstringExchange-specific publisher ID.Always
namestringMain seller/entity or publisher name (may be aliased at the publisher’s request).Sometimes

For additional publisher enrichment fields, see Supplemental Data.


Content Object

Last updated on August 9, 2019

BidRequest.app.content or BidRequest.site.content


The Content object describes the type of content of the App or Site in which the ad is displayed. The OpenX implementation currently supports a subset of the OpenRTB Content object.

This section contains some Beta out-stream content for Video. If you are already consuming out-stream bid requests, you may be able to use the same style parsing for out-stream when you consume your OpenX bid requests. If you aren’t already consuming out-stream bid requests and are interested in doing so, we advise you build toward the IAB’s OpenRTB 2.5 specification, leveraging the new placement field for the Video object. Please reach out to your OpenX Platform Development Manager if you have any questions.

Field nameData typeDescriptionSent?
catstring arrayArray of IAB content categories that describe the content producer. See list 5.1 in the OpenRTB 2.5 specification. 
contextstring(In Beta and not part of the IAB’s OpenRTB 2.5 specification) An attribute that infers out-stream inventory when the following values are passed:
   • 101: In-read, an out-stream ad format that is placed within the text of a site or app
   • 102: In-board, an out-stream ad format that is located at the top of a page

Note: If you’re new to out-stream, please be advised that we are working toward support of the IAB’s OpenRTB 2.5 specification. This specification defines the future IAB industry standard for out-stream and its subtypes as the Video object’s new placement field. Please contact your OpenX Platform Development Manager for more details.
Sometimes
lenintegerLength of content in seconds; appropriate for video or audio. 
qagmediaratingintegerThe quality assurance guidelines’ (QAG) media rating. For details, the IAB’s OpenRTB 2.5 specification.Sometimes
titlestringContent title.
Video Examples: Search Committee (television), A New Hope (movie), or Endgame (made for Web).
Non-Video Example: Why an Antarctic Glacier Is Melting So Quickly (Time magazine article).
 

For additional details, see:


Device Object

Last updated on September 11, 2019

BidRequest.device


Each BidRequest object may contain a Device object, which provides details about the end-user’s computing environment. The Device object can contain an Extensions object (see below) and can reference the Geo object.

Field nameData typeDescriptionSent?
uastringThe HTTP user agent, which typically indicates the user’s browser. For example, “Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_2; en-us)”Sometimes
geogeo objectAn object containing properties that describe the geographic location of the user as derived from the device.Sometimes
dntintegerThe “do not track” flag. This flag indicates whether the user’s web browser is set for private browsing.
   • 0 = False
   • 1 = True (Browser is set for private browsing.)
Sometimes
lmtintegerThe “limit tracking” flag. If the user’s mobile device is set for private browsing, the LMT (limit tracking) flag is passed.
   • 0 = False
   • 1 = True (The user does not want to be tracked.)
Sometimes
ipstringThe ipv4 address closest to the user’s device. For example, 238.122.7.1Sometimes
ipv6stringThe IP address closest to device as IPv6.Sometimes
devicetypeintegerThe detected device category for the user’s device as defined in the IAB’s OpenRTB 2.5 specification.

Note: OpenX OpenRTB uses a devicetype value of 1001 to indicate text (SMS).
Sometimes
makestringThe make for the user’s device. For example, AppleSometimes
modelstringThe model for the user’s device. For example, iPhoneSometimes
osstringThe operating system for the user’s device. For example, iOSSometimes
osvstringThe version number for the user’s operating system. For example, 3.1.2Sometimes
hwvstringThe device’s hardware version. For example, 5S (for iPhone 5S)Sometimes
hintegerThe physical height of the device’s screen, in pixels.Sometimes
wintegerThe physical width of the device’s screen, in pixels.Sometimes
languagestringA single two-letter code ISO 639-1 for the user’s preferred browsing language on their device. For example, enSometimes
carrierstringThe carrier or ISP using exchange-curated string names. Should be published to bidders a priori. For example, VERIZONSometimes
mccmncstringThe mobile carrier for the user’s device as the concatenated MCC-MNC code. Refer to https://en.wikipedia.org/wiki/Mobile_country_code for additional examples.
Note: The dash between the MCC and MNC parts is required to remove parsing ambiguity. For example, 310-005 (Identifies Verizon Wireless CDMA in the USA.)
Sometimes
connectiontypeintegerThe detected data connection type for the user’s device as defined in the IAB’s OpenRTB 2.5 specification. For example, 2Sometimes
ifastringThe ID for advertisers (also referred to as “IDFA”). This is the ID sanctioned for advertiser use in the clear (not hashed).Sometimes
didsha1stringThe SHA-1 hash identifier for the user’s device, such as the UDID for an iOS device. For example, 2b6f0cc904d137be2e1730235f5664094b831186Sometimes
dpidsha1stringThe SHA-1 hash of the Android ID for the end-user’s mobile device.Sometimes
dpidmd5stringThe MD5 hash of the Android ID for the end-user’s mobile device.Sometimes
macsha1stringThe SHA-1 hash of the device’s MAC address.Sometimes
macmd5stringThe MD5 hash of the device’s MAC address.Sometimes
extextension objectAn object containing properties that describe custom fields related to this device.Sometimes

For additional details, see:

BidRequest.device.ext


To provide additional details about the end-user’s device, the Device object may include an Extensions object.

Field nameData typeDescriptionSent?
languagearray of stringsAn array of two-letter codes for the user’s preferred browsing languages on their device, listed in order of the user’s language preferences in the browser.Always

Geo Object

Last updated on April 18, 2017

BidRequest.device.geo or BidRequest.user.geo


The Geo object provides details about the user’s current location (in relation to the Device object) or their primary location (via the User object).

Each Geo object can include the optional Extensions object (see below).

Field nameData typeDescriptionSent?
citystringThe city where the user is located (United Nations Code for Trade and Transport Locations).
For example, los angeles
Sometimes
countrystringThe country where the user is located expressed as an ISO 3166-1 alpha-3 code.
For example, USA
Sometimes
extextensions object
(see below)
An object containing properties that describe custom fields related to the end-user’s physical location.Sometimes
latfloating-pointThe user’s latitude. For example, 33.684Sometimes
lonfloating-pointThe user’s longitude. For example, -117.793Sometimes
region
(new)
stringIndicates the region code per ISO-3166-2 or the two-character state code in the U.S.
For example, CA
Sometimes
typeintegerIndicates the source of the user’s geographic location details, as defined in the IAB’s OpenRTB 2.5 specification.
For example, this field can indicate whether the lat or lon is derived from the device’s GPS location or an IP address.
Sometimes
zipstringThe user’s postal code location. Values are not restricted to the U.S.
For example, 92602
Sometimes

For additional details, see:

BidRequest.device.geo.ext or BidRequest.user.geo.ext


To provide additional details about the end-user’s physical location, the Geo object may include an Extensions object.

Field nameData typeDescriptionSent?
continentstringThe user’s continent location.
For example, north america
Sometimes
dmaintegerThe user’s designated market area (DMA) location.Sometimes

User Object

Last updated on April 12, 2019

BidRequest.user


Each BidRequest object can contain a User object, which provides details about the end-user.

The User object can contain an Extensions object and can reference the user’s Geo via their Device.

NOTE

With the enactment of the General Data Protection Regulation (GDPR), OpenX includes GDPR-specific elements in its support of OpenRTB. For more information, please contact your OpenX Platform Development Manager. See also Regs object.

Field nameData typeDescriptionSent?
buyeruidstringOpenX can return data to the bidder that was previously synced with OpenX and tracked by an OpenX cookie. For example, the bidder’s unique identifier for a user could be synchronized and later reported back to the bidder when the user’s cookie data becomes available.Sometimes
dataarray (data object)An array of Data objects to provide details about the user.Sometimes
extextensions objectAn object containing properties that describe custom fields related to this user,Sometimes
genderstringThe end-user’s gender (M, F, or O)Sometimes
geogeo objectAn object containing properties that describe the user’s primary location, which is not necessarily their current locationSometimes
idstringThe OpenX ID for the user, which is only returned when OpenX is able to set the cookie for the user. To protect the identity of the user, the ID is different for each bidder.
For example, Ad Exchange may send a value of 1234 to bidder A and a value of 5678 to bidder B to represent the same user.
Sometimes
yobintegerThe end-user’s four digit year of birth. For example, 1972Sometimes

For additional publisher enrichment fields, see Supplemental Data.

To provide additional details about the end-user, Ad Exchange may include an Extensions object.

BidRequest.user.ext


Field nameData typeDescriptionSent?
consentstringDeclaration that the user has consented to having his or her data collected by the publisher’s site, as mandated by the GDPR.Sometimes
consented_providers_settingsobjectInformation about Google providers for whom the publisher has informed Google that its European Economic Area (EEA) users have consented to the use of their personal data for ad personalization. This field is only relevant for requests that are subject to GDPR.

Note: This object is only populated for Google Exchange Bidding traffic.
Sometimes
eidsobject arrayIncorporates external identifiers related to user data.Sometimes
BidRequest.user.ext.consented_providers_settings


Field nameData typeDescriptionSent?
consented_providersinteger arraySet of Google IDs corresponding to Google providers for whom the publisher has informed Google that its European Economic Area (EEA) users have consented to the use of their personal data for ad personalization. Google has publicly provided a .csv file containing the mapping of provider IDs to provider names.

Note: This field is only populated for Google Exchange Bidding traffic.
Sometimes
BidRequest.user.ext.eids


Field nameData typeDescriptionSent?
sourcestringThe source of the external identifier, typically a top-level domain URL, such as adsrver.org.Sometimes
uidsobject arrayAn array of unified identifiers that are mapped, for standardization, to user IDs collected by exchange partners who adopt a given standard.Sometimes
BidRequest.user.ext.eids.uids


Field nameData typeDescriptionSent?
idstringOne of the IDs in a uids array.Sometimes
extextensions objectAn object containing properties that describe custom fields related to a unified ID.Sometimes
BidRequest.user.ext.eids.uids.ext


Field nameData typeDescriptionSent?
rtiPartnerstringThe name of the real-time identity partner.Sometimes

See also, OpenRTB Advisory-GDPR.


Data Object

Last updated on June 1, 2016

BidRequest.user.data


The Data object provides details about the user.

NOTE

This object is supported, but not currently populated. Ask your Platform Development Manager for more details.

Field nameData typeDescriptionSent?
idstringA unique OpenX identifier for the data provider. This field includes any publisher data that may be provided in the BidRequest using a Data object and corresponding segments.

Publishers can pass a value that may be included in the BidRequest.data.id field if its value is either publisher or it is prefixed with pub- followed by any value of their choosing.
For example, pub-12345678.
Values passed by publishers and prefixed with pub- have not been verified by OpenX.

Note: The conventions used by this field will change as OpenX supports additional sources of data.
Sometimes
namestringThe name of the data provider.Sometimes
segmentarray segment objectA collection of Segment objects, each describing a particular data point available from this data providerSometimes

For additional publisher enrichment fields, see Supplemental Data.


Segment Object

Last updated on March 8, 2016

BidRequest.user.data.segment


The Segment object provides data about the user.

NOTE

This object is supported, but not currently populated. Ask your Platform Development Manager for more details.

Field nameData typeDescriptionSent?
idstringThe ID of the data segment specific to the data provider.Sometimes
namestringThe name of the data segment specific to the data provider. For example, gender, dma, or age.Sometimes
valuestringA string representation of the data segment value.Sometimes

For additional publisher enrichment fields, see Supplemental Data.


Regs Object

Last updated on December 17, 2019

BidRequest.regs


With the enactment of the General Data Protection Regulation (GDPR), OpenX includes GDPR-specific elements in its support of OpenRTB. For more information, please contact your OpenX Platform Development Manager. See also User object.

The Regs object provides details about any regulations applicable to the request.

Field nameData typeDescriptionSent?
coppaintegerIndicates whether the request is subject to the Children’s Online Privacy Protection Act (COPPA) regulations.
   • 0 = false
   • 1 = true (the request is subject to COPPA)
Sometimes
extextensions objectAn object containing properties that describe custom fields for additional regulations.Sometimes
BidRequest.regs.ext


The optional Extensions object can provide additional regulatory details.

Field nameData typeDescriptionSent?
gdprintegerIndicates whether the request is subject to the General Data Protection Regulation (GDPR).
   • 0 = false
   • 1 = true (the request is subject to GDPR)
Sometimes
sb568integerIndicates whether the request is subject to California’s SB-568 regulations.
   • 0 = false
   • 1 = true (the request is subject to SB-568)
Sometimes
us_privacystringMust follow the U.S. Privacy string format. See table below. Click here for more information on CCPA Integration Support.Optional
us_privacy string


The us_privacy string consists of the following components.

String componentExpected valuesDescription
Specification versionnumber

(1 char in string)
The version of this string specification used to encode the string.
Explicit notice / Opportunity to opt outenum
(N = No, Y = Yes, - = Not applicable)
Has explicit notice been provided as required by 1798.115(d) of the CCPA and the opportunity to opt out of the sale of their data pursuant to 1798.120 and 1798.135 of the CCPA.
Opt-out saleenum
(N = No, Y = Yes, - = Not applicable)
Has user opted-out of the sale of his or personal information pursuant to 1798.120 and 1798.135.
LSPAenum
(N = No, Y = Yes, - = Not applicable)
Publisher is a signatory to the IAB Limited Service Provider Agreement (LSPA) and the publisher declares that the transaction is covered as a Covered Opt Out Transaction or a Non Opt Out Transaction as those terms are defined in the Agreement.


See also:


Pmp Object

Last updated on February 15, 2018

BidRequest.imp.pmp


The Imp object can contain a Pmp object, which describes deals eligible for impressions.

If the Pmp object is sent, its fields are always sent.

Field nameData typeDescriptionSent?
dealsarray
deal object
A collection of deal objects, each describing eligible deal terms for this impression opportunity.
This field is always sent when the Pmp object is sent.
Only when Pmp object is sent
private_auctionintegerIndicates a private auction restricted to certain seats (1) or that all bids are accepted (0).
   • If the bid request contains any MatchingAdIds objects that do not have an associated deal, then private_auction is 0.
   • If not, private_auction is 1 (only deal bids are accepted).
This field is always sent when the Pmp object is sent.
Only when Pmp object is sent

See also, PMP bid request sample.


Deal Object

Last updated on August 10, 2020

BidRequest.imp.pmp.deal


The Deal object (direct deals) describes a list of deals eligible for impressions. If the Deal object is sent, its at field is sent.

Field nameData typeDescriptionSent?
idstringA unique identifier for the deal.Always
atintegerAuction type of the PMP request. This overrides the overall auction type of the request.
   • 1: First-price auction.
   • 2: Second-price auction.
   • 3: Fixed price auction.

Note: Real-time guaranteed (RTG) requests are sent with both a value of 3 in the deal.at field and a value of 4 in the deal.ext.at field to maintain backwards compatibility. If using RTG, please set your logic to refer to the deal.ext.at field first, and then deal.at field to understand the auction type.
Always
bidfloorfloating-pointThe minimum price for the impression in CPM. The default value is 0.Always
BidRequest.imp.pmp.deal.ext


Field nameData typeDescriptionSent?
atintegerAdditional auction type:
4: Guaranteed deal.
Sometimes


See also:


Supplemental Data

To provide buyers with additional data about opportunities, OpenX offers its publishers an optional openrtb ad call parameter to send structured JSON data in each BidRequest about the user, the site or app, and other details.

Publishers may pass any supported fields at their own discretion. Publishers cannot pass certain OpenRTB fields. OpenX Ad Exchange may override the publisher’s data if it determines a value.

Click to see fields that can be passed by publishers


Object nameField nameOpenX may override?
AppkeywordsNo
ApppagecatYes
ApppaidYes
AppprivacypolicyNo
AppsectioncatYes
AppverNo
BannerapiNo
BannerbtypeYes
BannerexpdirNo
BannerhmaxYes
BannerhminYes
BannermimesNo
BannertopframeNo
BannerwmaxYes
BannerwminYes
BidRequesttestNo
ContentcatYes
ContentcontextNo
ContentembeddableNo
ContentepisodeNo
ContentkeywordsNo
ContentlanguageNo
ContentlenNo
ContentlivestreamNo
ContentseasonNo
ContentseriesNo
ContentsourcerelationshipNo
ContenttitleNo
ContenturlNo
ContentuseratingNo
ContentvideoqualityNo
DataidAdditive (Publishers and Ad Exchange can add Data objects)
DatanameAdditive (Publishers and Ad Exchange can add Data objects)
Devicedidmd5Yes
DeviceflashverYes
DevicehYes
DevicehwvYes
Deviceipv6Yes
DevicejsYes
Devicemacmd5Yes
Devicemacsha1Yes
DeviceppiYes
DevicepxratioYes
DevicewYes
GeocityYes
GeometroYes
GeoregionYes
Georegionfips104Yes
GeoutcoffsetYes
ImpdisplaymanagerYes
ImpdisplaymanagerverYes
ImpinstlYes
ImptagidYes
NativeapiNo
NativebattrNo
NativeverNo
ProducercatYes
ProducerdomainNo
ProduceridYes
ProducernameYes
PublishercatYes
SegmentnameAdditive (publishers and Ad Exchange can add data segments)
SegmentvalueAdditive (publishers and Ad Exchange can add data segments)
SitekeywordsNo
SitemobileYes
SitepagecatYes
SiteprivacypolicyNo
SitesearchYes
SitesectioncatYes
UserkeywordsNo