Bid Request Specification
note
BidMachine Ad Exchange currently works with Open RTB 2.3 and 2.5. This documentation is only valid for Open RTB 2.3.
Bid Request Object
Attribute | Type | Description | Example |
---|---|---|---|
id | string | Unique ID of the bid request, provided by the exchange. | d5260eec-75d9-4f7d-86bc-22b01b4c779e |
imp | object array | Array of Imp objects representing the impressions offered. At least 1 Imp object is required. | (empty) |
app | object | Details about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps. | (empty) |
device | object | Details about the user’s device to which the impression will be delivered. | (empty) |
user | object | Details about the human user of the device; the advertising audience. | (empty) |
test | integer; default 0 | Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode | 0 |
at | integer; default 2 | Auction type, where 1 = First Price, 2 = Second Price Plus. BidMachine currently supports only type 2 | 2 |
tmax | integer | Maximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline. | 250 |
cur | string array | Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies. | ["USD"] |
bcat | string array | Blocked advertiser categories using the IAB content categories. | ["IAB2-1"] |
badv | string array | Block list of advertisers by their domains. | ["blocked.domain.com"] |
reg | object | A Regs object that specifies any industry, legal, or governmental regulations in force for this request. | (empty) |
source | object | This object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange. | (empty) |
ext | object | Placeholder for exchange-specific extensions to OpenRTB | (empty) |
Imp
Attribute | Type | Description | Example |
---|---|---|---|
id | required,string | A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments OR UUID). | 6ba06f9a-44c8-497d-8bc3-78804bebc2c8 |
banner | object | A Banner object; required if this impression is offered as a banner ad opportunity. | (empty) |
video | object | A Video object; required if this impression is offered as a video ad opportunity. | (empty) |
native | object | A Native object; required if this impression is offered as a native ad opportunity. | (empty) |
displaymanager | required,string | Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customise ad code by a partner. Recommended for video and/or apps. | you_ssp_name |
displaymanagerver | required,string | Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customise ad code by a partner. Recommended for video and/or apps. | 2.0.0 |
instl | optional,integer; default 0 | 1 = interstitial/fullscreen, 0 = not interstitial. | 0 |
tagid | optional,string | Identifier for specific ad placement or ad tag that was used to initiate the auction. Useful for debugging or optimization. | my__debug__tag |
bidfloor | required,float; default 0 | Minimum bid for this impression expressed in CPM. | 0.15 |
bidfloorcur | optional,string; default "USD" | Currency (ISO-4217 alpha code). May differ from bid response currency if allowed by exchange. | USD |
secure | integer | Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP support can be assumed. | 0 |
ext | object | Placeholder for exchange-specific extensions to OpenRTB | (empty) |
Banner Object
Attribute | Type | Description | Example |
---|---|---|---|
w | integer | Width of the impression in pixels. If neither wmin nor wmax are specified, this value is an exact width requirement. Otherwise it is a preferred width. | 320 |
h | integer | Height of the impression in pixels. If neither hmin nor hmax are specified, this value is an exact height requirement. Otherwise it is a preferred height. | 50 |
wmax | integer | Maximum width of the impression in pixels. If included along with a w value then w should be interpreted as a recommended or preferred width. | 320 |
hmax | integer | Maximum height of the impression in pixels. If included along with an h value then h should be interpreted as a recommended or preferred height. | 50 |
wmin | integer | Minimum width of the impression in pixels. If included along with a w value then w should be interpreted as a recommended or preferred width. | 320 |
hmin | integer | Minimum height of the impression in pixels. If included along with an h value then h should be interpreted as a recommended or preferred height. | 50 |
id | string | Unique identifier for this banner object. Recommended when Banner objects are used with a Video object to represent an array of companion ads. Values usually start at 1 and increase with each object; should be unique within an impression. | ap1gm-0jioruind-1ffopjgo1p |
btype | integer array | Blocked banner ad types. | [2] |
battr | integer array | Blocked creative attributes. BidMachine currently blocks: "Expandable (User Initiated - Rollover)", "Pop (e.g., Over, Under, or Upon Exit)", "Provocative or Suggestive Imagery", "Shaky, Flashing, Flickering, Extreme Animation, Smileys", "Windows Dialog or Alert Style" | [5,8,9,10,14] |
pos | integer | Ad position on screen. | 5 |
mimes | string array | Content MIME types supported. BidMachine supports: "image/png" , "text/javascript" , "text/html" , "image/jpg" , "image/gif" . | ["image/jpg","image/gif","image/png"] |
topframe | integer | Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes. | 1 |
api | integer array | List of supported API frameworks for this impression. If not explicitly listed, it is assumed not to be supported. | [5,3] |
ext | object | Placeholder for exchange-specific extensions to OpenRTB. | {"bannertype":"rewarded"} |
Native
Attribute | Type | Description | Example |
---|---|---|---|
request | string | Request payload complying with the Native Ad Specification. | "89oghjnr" |
ver | string | Version of the Native Ad Specification to which request complies; highly recommended for efficient parsing. | "1.0" |
api | integer array | List of supported API frameworks for this impression. If not explicitly listed, assumed unsupported. | [1] |
battr | integer array | Blocked creative attributes. | [5,3] |
Video
Attribute | Type | Description | Example |
---|---|---|---|
mimes | string array | Content MIME types supported. | ["video/mp4"] |
minduration | integer | Minimum video ad duration in seconds. | 5 |
maxduration | integer | Maximum video ad duration in seconds. | 30 |
protocol | integer | Supported video bid response protocol. Use of protocols is recommended. At least one must be specified in either. | [1] |
protocols | integer array | Array of supported video bid response protocols. | [1,2,6] |
w | integer | Width of the video player in pixels. | 320 |
h | integer | Height of the video player in pixels. | 480 |
startdelay | integer | Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. | 1 |
linearity | integer | Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed. | 1 |
battr | integer array | Blocked creative attributes. IMPORTANT: if you need rewarded video — send [16] here. | [1,3] |
minbitrate | integer | Minimum bit rate in Kbps. Exchange may set this dynamically or universally across publishers. | 128 |
maxbitrate | integer | Maximum bit rate in Kbps. Exchange may set this dynamically or universally across publishers. | 512 |
playbackmethod | integer array | Allowed playback methods. If none specified, assume all are allowed. | [1,2,3,4] |
delivery | integer array | Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported. | [1,2] |
pos | integer | Ad position on screen. | [3] |
companiodad | object array | Array of banner objects if companion ads are available. | (empty) |
api | integer array | Supported API frameworks. If not listed, assumed unsupported. | [1,2,3,4,5] |
companiontype | integer array | Supported VAST companion ad types. Recommended if companion Banner objects are included. | [1] |
App Object
Attribute | Type | Description | Example |
---|---|---|---|
id | string | Exchange-specific app ID. | "102938" |
name | string | App name (may be aliased at the publisher’s request). | "TestApp" |
bundle | string | Application bundle or package name (e.g., com.app.game); intended to be a unique ID across exchanges. iOS will pass the app store ID, android – the package bundle. | android: "com.app.test" iOS: "78945611" |
domain | string | Domain of the app. | "game.app.com" |
storeurl | string | App store URL for an installed app; for QAG 1.5 compliance. | https://itunes.apple.com/us/app/somerandomapp/id1191231238?mt=8 |
cat | string array | Array of IAB content categories of the app. | ["IAB2-1", "IAB2-4"] |
sectioncat | string array | Array of IAB content categories that describe the current section of the app. | ["IAB2"] |
pagecat | string array | Array of IAB content categories that describe the current page or view of the app. | ["IAB2-1"] |
ver | string | Application version. | "1.0.3" |
privacypolicy | integer | Indicates if the app has a privacy policy, where 0 = no, 1 = yes. | 1 |
paid | integer | 0 = app is free, 1 = the app is a paid version. | 1 |
publisher | object | Details about the Publisher of the app. | (empty) |
keywords | string | Comma separated list of keywords about the app. | "automotive" |
ext | object | Placeholder for exchange-specific extensions to OpenRTB. BidMachine sends sdk version, time of the session, session id, app uptime, number of impressions and clicks. | { "sdk": "2.0.0", "session_uptime": 36, "session_id": 56, "app_uptime": 31995, "impressions_count": 142, "clicks_count": 27 } |
Device Object
Attribute | Type | Description | Example |
---|---|---|---|
ua | string | Browser user agent string. | "Mozilla/5.0 (iPhone; CPU iPhone OS 10_2 like Mac OS X) AppleWebKit/602.3.12 (KHTML, like Gecko) Mobile/14C89" |
geo | object | Location of the device assumed to be the user’s current location defined by a Geo object. | (empty) |
dnt | integer | "Do Not Track" flag: 0 = unrestricted, 1 = do not track. | 0 |
lmt | integer | "Limit Ad Tracking" flag: 0 = unrestricted, 1 = limited per commercial guidelines. | 1 |
ip | string | IPv4 address closest to device. | "23.227.207.23" |
ipv6 | string | IPv6 address closest to device. | (empty) |
devicetype | integer | The general type of device. | 4 |
make | string | Device make. | "Apple" |
model | string | Device model. | "iPhone" |
os | string | Device operating system. | "iOS" |
osv | string | Device operating system version. | "10.1.3" |
hmw | string | Hardware version of the device. | "5S" |
h | integer | Physical height of the screen in pixels. | 568 |
w | integer | Physical width of the screen in pixels. | 320 |
ppi | integer | Screen size in pixels per linear inch. | 326 |
pxratio | float | Ratio of physical pixels to device-independent pixels. | 2 |
js | integer | Support for JavaScript: 0 = no, 1 = yes. | 1 |
language | string | Browser language using ISO-639-1-alpha-2. | "en" |
carrier | string | Carrier or ISP (e.g., "VERIZON"). "WIFI" is used to indicate high bandwidth. | (empty) |
connectiontype | integer | Network connection type. | 2 |
ifa | string | ID sanctioned for advertiser use in the clear (i.e., not hashed). | 382A78A3-7EA0-4D3B-9724-0231C07D0C5A |
didsha1 | string | Hardware device ID (e.g., IMEI), hashed via SHA1. | 9db9123123b7fe382df2efeeb0176d2216cff7e |
didmd5 | string | Hardware device ID (e.g., IMEI), hashed via MD5. | 12f2f79bb5b7fe382df2efeeb0176da2216cff7e |
dpidsha1 | string | Platform device ID (e.g., Android ID), hashed via SHA1. | a12f1479bb5b7fe382df2efeeb0176d16cff7e |
dpidmd5 | string | Platform device ID (e.g., Android ID), hashed via MD5. | 12sff9bb5b7fe382df2efeeb0176d2216cff7e |
macsha1 | string | MAC address of the device, hashed via SHA1. | 12sff9bb5b7fe382df2efeeb0176d2216cff7e |
macmd5 | string | MAC address of the device, hashed via MD5. | 12sff9bb5b7fe382df2efeeb0176d2216cff7e |
ext | object | Placeholder for exchange-specific extensions. BidMachine sends info about battery state and rooted flag. | {"battery": -100, "rooted": "false"} |
User Object
Attribute | Type | Description | Example |
---|---|---|---|
id | string | Exchange-specific ID for the user. At least one of id or buyerid is recommended. | "1" |
buyerid | string | Buyer-specific ID for the user as mapped by the exchange for the buyer. At least one of buyerid or id is recommended. | "1" |
yob | integer | Year of birth as a 4-digit integer. | 1984 |
gender | string | Gender, where "M" = male, "F" = female, "O" = other. (Omitted means unknown) | "O" |
keywords | string | Comma-separated list of keywords, interests, or intent. | "game" |
geo | object | Location of the user’s home base defined by a Geo object. This is not necessarily their current location. | (empty) |
data | object array | Additional user data. Each Data object represents a different data source. | (empty) |
ext | object array | Placeholder for exchange-specific extensions to OpenRTB. | {"consent" : "1"} |
Data Object
Attribute | Type | Description | Example |
---|---|---|---|
id | string | Exchange-specific ID for the data provider. | "2" |
name | string | Exchange-specific name for the data provider. | "test" |
segment | object array | Array of Segment objects that contain the actual data values. | (empty) |
Segment Object
Attribute | Type | Description | Example |
---|---|---|---|
id | string | ID of the data segment specific to the data provider. | "12" |
name | string | Name of the data segment specific to the data provider. | "address" |
value | string | String representation of the data segment value. | "Delaware, Wilmington, 19809, United States" |
Geo Object
Attribute | Type | Description | Example |
---|---|---|---|
lat | float | Latitude from -90.0 to +90.0, where negative is south. | 15 |
lon | float | Longitude from -180.0 to +180.0, where negative is west. | 30 |
type | integer | Source of location data; recommended when passing lat/lon. | 2 |
country | string | Country code using ISO-3166-1-alpha-3 | "USA" |
region | string | Region code using ISO-3166-2; 2-letter state code if USA. | "US" |
city | string | City using United Nations Code for Trade & Transport Locations. See Appendix A for a link to the codes. | "New York" |
zip | string | Zip or postal code. | "19809" |
utcoffset | integer | Local time as the number +/- of minutes from UTC. | 180 |
Publisher Object
Attribute | Type | Description | Example |
---|---|---|---|
id | string | Exchange-specific publisher ID. | "12" |
name | string | Publisher name (may be aliased at the publisher’s request). | "test_name" |
cat | string array | Array of IAB content categories that describe the publisher. | ["IAB2-1"] |
domain | string | Highest level domain of the publisher. | "publisher.com" |
GDPR
Parameter | Type | Values | Example Values |
---|---|---|---|
regs.ext.gdpr | integer | 0 : GDPR does not apply to this traffic 1 : GDPR applies to this traffic | 0 |
user.ext.consent | string | Consent string per IAB TCF spec. Also supports:"0" : consent NOT given"1" : consent given | "BOJObISOJObISAABAAENAA4AAAAAoAAA" |
Regs
Attribute | Type | Description | Example |
---|---|---|---|
coppa | integer | Flag indicating if this request is subject to COPPA regulations (USA FTC), where 0 = no, 1 = yes. | 1 |
ext | object | Extension for GDPR information. | { "gdpr": 0 } |
Source Object
Attribute | Type | Description | Example |
---|---|---|---|
fd | int | Entity responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source. | 1 |
tid | string | Transaction ID that must be common across all participants in this bid request (e.g., potentially multiple exchanges). | 6ba06f9a-44c8-497d |
pchain | string | Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0. | 7tury102i-7uf7 |
ext | object | Placeholder for exchange-specific extensions to OpenRTB. | (empty) |
Source Ext Object
info
ext
object is used to provide schain info. It goes under source.ext.schain path
Attribute | Type | Description | Example |
---|---|---|---|
ext.schain | object | This object represents both the links in the supply chain as well as an indicator whether or not the supply chain is complete. | (empty) |
Schain Object Properties
info
For more information please refer to official IAB documentation
Attribute | Type | Description | Example |
---|---|---|---|
complete | integer | Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or other medium of the inventory, where 0 = no, 1 = yes. | 1 |
nodes | object array | Array 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. In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request. | (empty) |
ver | string | Version of the supply chain specification in use, in the format of "major.minor" (e.g., "1.0" ). | "1.0" |
ext | object | Placeholder for advertising-system specific extensions to this object. | (empty) |
Nodes Object Properties
Attribute | Type | Description |
---|---|---|
asi | string | The canonical domain name of the SSP, Exchange, Header Wrapper, etc., that bidders connect to. This may differ from the parent corporate domain to support WHOIS and reverse IP lookups. Should match the value used in ads.txt if available. |
sid | string | Identifier for the seller/reseller account within the advertising system. Typically maps to publisher.id in OpenRTB or the publisher’s org ID in OpenDirect. Max length: 64 characters. |
rid | string | The request.id as issued by this seller. |
name | string | Legal company name paid for inventory. Should be omitted if listed in sellers.json . (optional) |
domain | string | Business domain of the represented entity. Should be omitted if listed in sellers.json . (optional) |
hp | integer | Indicates if this node is involved in payment flow. 1 = involved, 0 = not involved. Required in version 1.0; future versions may support non-payment nodes. |
ext | object | Placeholder for system-specific extensions. |
User Contextual Data
note
User Level Contextual Data is defined by the SDK but can be overwritten by an App/Mediation via the SDK API
Name | Type | Description | Example |
---|---|---|---|
request.context.user.ext.impdepth | uint32 | The count of impressions for a specific placement type in a given app session. Deprecated in 3.0.0 | 5 |
request.context.user.ext.sessionduration | uint64 | The total duration of time a user has spent so far in a specific app session expressed in seconds. | 55 |
request.context.user.ext.lastbundle | string | The last app bundle the user saw on the previous impression in a given session per placement type. Deprecated in 3.0.0 | "bundle" |
request.context.user.ext.lastadomain | string | The last advertiser domain the user saw on the previous impression in a given session per placement type. Deprecated in 3.0.0 | "domain" |
request.context.user.ext.clickrate | float | The percentage of clicks/impressions per user per placement type over a given number of impressions, where 5 represents a 5% CTR. Applies only to Rewarded and Video. Deprecated in 3.0.0 | 5 |
request.context.user.ext.lastclick | bool | Indicates if the user clicked on the last impression, where 1 = clicked, 0 = didn’t click. Deprecated in 3.0.0 | 1 |
request.context.user.ext.completionrate | float | Percentage of completions/impressions per user for a given number of impressions, where 70 represents 70% completion. Deprecated in 3.0.0 | 70 |
Device Contextual Data
Name | Type | Description | Example |
---|---|---|---|
request.context.device.ext.inputlanguage | list[string] | List of user languages. | ["DE", "US"] |
request.context.device.ext.diskspace | double | Value of available free disk space. | 61347.0 |
request.context.device.ext.totaldisk | double | Value of total disk space. | 112221.0 |
request.context.device.ext.ringmute | bool | Device sound setting at ad request time. | 1 - yes , 0 - no |
request.context.device.ext.charging | bool | Is the device charging. | 1 - yes , 0 - no |
request.context.device.ext.batterylevel | float | Battery level. 1 - full charge, 0.1 - 10%, 0 - empty. | — |
request.context.device.ext.batterysaver | bool | Battery saver enabled. | 1 - yes , 0 - no |
request.context.device.ext.darkmode | bool | Dark mode enabled. | 1 - yes , 0 - no |
request.context.device.ext.airplane | bool | (Android only) Airplane mode enabled. | 1 - yes , 0 - no |
request.context.device.ext.dnd | bool | (Android only) "Do Not Disturb" setting enabled. | 1 - yes , 0 - no |
request.context.device.ext.devicename | string | User-defined name of the device. | iPhone 14 Pro |
request.context.device.ext.time | uint64 | POSIX timestamp, depends on device settings. | 1680197719.5890589 |
request.context.device.ext.headset | bool | Is a wired headset connected. | 1 - yes , 0 - no |
request.context.device.ext.headsetname | string | Identifier of connected wireless headset. | "Headset" |
request.context.device.ext.screenbright | double | Brightness level of screen from 0.0 to 1.0. | 0...1 |
request.context.device.ext.jailbreak | bool | Is the device jailbroken. | 1 - yes , 0 - no |
request.context.device.ext.lastbootup | uint64 | Android: ms since boot incl. sleep. iOS: POSIX timestamp of last boot. | 1676623341.589673 |
request.context.device.ext.totalmem | uint64 | Total RAM in bytes. | 34359738368 B |
request.context.device.ext.atts | int | (iOS only) App tracking authorization status: 0 - Not Determined, 1 - Restricted, 2 - Denied, 3 - Authorized. | — |
App Contextual Data
Name | Type | Description | Example |
---|---|---|---|
request.context.app.ext.install_time | uint64 | Unix timestamp in milliseconds of the application install (might be zero). Available since SDK 3.0.1 | 0.0 |
request.context.app.ext.first_launch_time | uint64 | Unix timestamp in milliseconds of the first BidMachine SDK launch. Available since SDK 3.0.1 and data can be incorrect for devices updated from older app/sdk version | 1.725296223359E12 |
request.context.app.ext.min_api_level | uint32 | (Android only) Minimal supported Android SDK version. | 21 |
request.context.app.ext.kotlin_version | string | Kotlin runtime version. | 1.8.20 |