You are here: Demand Partners > Real-time bidding > OpenRTB API > BidRequest object

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 requestWhen 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 impressionA 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 requestCommunication 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.

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

Always
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.

Sometimes
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 appSynonymous 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.

Sometimes
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

Sometimes
user User object

An object containing properties that describe the user viewing the impression

Sometimes

test

(new)

integer

Indicates test mode (1), which is not billable

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

Sometimes

at

integer

Auction type of the request.

Always
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.

Always
bcat array (string)

The list of advertiserIn OpenX, an account type that represents a business that runs advertising campaigns to display ads on websites. categories that the publisherAn 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 OpenRTB API 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 OpenRTB API 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

Sometimes
badv array (string)

Blocked advertiser, the list of top-level advertiser domains (for example, blockeddomain.com) blocked for this publisher as derived from the click URL.

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

source

Source object

An object that provides data about the inventoryAd 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

Sometimes
ext Extensions object

An object containing custom fields that describe the BidRequest

Sometimes

Additional publisher enrichment fields

Extensions object

BidRequest.ext

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

Field name Data type Description Sent?

tp_key_val

ThirdPartyKeyValue

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

Sometimes

ThirdPartyKeyValue object

BidRequest.ext.tp_key_val

Field name Data type Description Sent?

key

string

The third-party identifier key

Sometimes

value

string

The value for the associated key

Sometimes

Feedback form