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

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