BidRequest object

Last updated on November 1, 2017

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 requestClosedWhen OpenX Ad Exchange receives an ad request, it sends a communication containing details about the impression to selected real-time bidders to solicit bids for it. contains a BidRequest object, a single Imp object, and may include other objects to provide additional information about the impressionClosedA single display of an ad on a web page, mobile app, or other delivery medium. For deals, impression is a metric to relay the total number of ads that have served. See also billable impression, forecasted impressions..

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:

BidRequest object

Field name Data type Description Sent?
id string

A unique ID for the request, which OpenX Ad Exchange uses to identify the auction.

For example: "888b4a7a-d259-11e0-9912-000c29b0c11a"

If the ad requestClosedCommunication from a web browser or app to an ad server to display an ad. includes multiple ad sizes, you will see multiple bid requests with the same ID. However, they represent one bid request that allows buyers to bid on different sizes.

imp array (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 unitClosedThe smallest inventory component that represents the space on a site where ads display. as a separate ad request.

site Site object

An object containing properties that describe the website where the ad will display if the bid request is for an impression on a website

The bid request can only have a Site or an App object.

app App object

An object containing properties that describe the app where the ad will display if the bid request is for an impression within a mobile appClosedSynonymous with mobile. Refers to the use of an app via a mobile device, specifically to differentiate from mobile web.

A bid request can only have an App or a Site object.

device Device object

An object containing properties that describe the device through which the impression is viewed, such as on a specific type of mobile phone

user User object

An object containing properties that describe the user viewing the impression





Indicates test mode (1), which is not billable

The default is 0, which indicates that the auction is billable.




Auction type of the request.

cur array (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.

bcat array (string)

The list of advertiser categories that the publisherClosedAn account type that represents a business with ad space to sell. wants to block for the ad request.

The BidRequest.bcat field supports the IAB categories listed in the IAB's OpenRTB 2.5 specification.

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.

OpenX bcat values:

  • 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

badv array (string)

Blocked advertiser, the list of top-level advertiser domains (for example, 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.



Source object

An object that provides data about the inventoryClosedAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit. source and which entity makes the final decision.

Always (when enabled)

regs Regs object

An object containing properties that describe any regulations applicable to the request

ext Extensions object

An object containing custom fields that describe the BidRequest


Additional publisher enrichment fields

Extensions object


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

Field name Data type Description Sent?



An object containing a list of third-party key-value pairs


ThirdPartyKeyValue object


Field name Data type Description Sent?



The third-party identifier key




The value for the associated key