Skip to main content

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

AttributeTypeDescriptionExample
idstringUnique ID of the bid request, provided by the exchange.d5260eec-75d9-4f7d-86bc-22b01b4c779e
impobject arrayArray of Imp objects representing the impressions offered. At least 1 Imp object is required.(empty)
appobjectDetails about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps.(empty)
deviceobjectDetails about the user’s device to which the impression will be delivered.(empty)
userobjectDetails about the human user of the device; the advertising audience.(empty)
testinteger; default 0Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode0
atinteger; default 2Auction type, where 1 = First Price, 2 = Second Price Plus. BidMachine currently supports only type 22
tmaxintegerMaximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline.250
curstring arrayArray of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies.["USD"]
bcatstring arrayBlocked advertiser categories using the IAB content categories.["IAB2-1"]
badvstring arrayBlock list of advertisers by their domains.["blocked.domain.com"]
regobjectA Regs object that specifies any industry, legal, or governmental regulations in force for this request.(empty)
sourceobjectThis object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange.(empty)
extobjectPlaceholder for exchange-specific extensions to OpenRTB(empty)

Imp

AttributeTypeDescriptionExample
idrequired,stringA 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
bannerobjectA Banner object; required if this impression is offered as a banner ad opportunity.(empty)
videoobjectA Video object; required if this impression is offered as a video ad opportunity.(empty)
nativeobjectA Native object; required if this impression is offered as a native ad opportunity.(empty)
displaymanagerrequired,stringName 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
displaymanagerverrequired,stringVersion 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
instloptional,integer; default 01 = interstitial/fullscreen, 0 = not interstitial.0
tagidoptional,stringIdentifier for specific ad placement or ad tag that was used to initiate the auction. Useful for debugging or optimization.my__debug__tag
bidfloorrequired,float; default 0Minimum bid for this impression expressed in CPM.0.15
bidfloorcuroptional,string; default "USD"Currency (ISO-4217 alpha code). May differ from bid response currency if allowed by exchange.USD
secureintegerFlag 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
extobjectPlaceholder for exchange-specific extensions to OpenRTB(empty)
AttributeTypeDescriptionExample
wintegerWidth 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
hintegerHeight 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
wmaxintegerMaximum 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
hmaxintegerMaximum 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
wminintegerMinimum 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
hminintegerMinimum 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
idstringUnique 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
btypeinteger arrayBlocked banner ad types.[2]
battrinteger arrayBlocked 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]
posintegerAd position on screen.5
mimesstring arrayContent MIME types supported. BidMachine supports: "image/png", "text/javascript", "text/html", "image/jpg", "image/gif".["image/jpg","image/gif","image/png"]
topframeintegerIndicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.1
apiinteger arrayList of supported API frameworks for this impression. If not explicitly listed, it is assumed not to be supported.[5,3]
extobjectPlaceholder for exchange-specific extensions to OpenRTB.{"bannertype":"rewarded"}

Native

AttributeTypeDescriptionExample
requeststringRequest payload complying with the Native Ad Specification."89oghjnr"
verstringVersion of the Native Ad Specification to which request complies; highly recommended for efficient parsing."1.0"
apiinteger arrayList of supported API frameworks for this impression. If not explicitly listed, assumed unsupported.[1]
battrinteger arrayBlocked creative attributes.[5,3]

Video

AttributeTypeDescriptionExample
mimesstring arrayContent MIME types supported.["video/mp4"]
mindurationintegerMinimum video ad duration in seconds.5
maxdurationintegerMaximum video ad duration in seconds.30
protocolintegerSupported video bid response protocol. Use of protocols is recommended. At least one must be specified in either.[1]
protocolsinteger arrayArray of supported video bid response protocols.[1,2,6]
wintegerWidth of the video player in pixels.320
hintegerHeight of the video player in pixels.480
startdelayintegerIndicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.1
linearityintegerIndicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed.1
battrinteger arrayBlocked creative attributes. IMPORTANT: if you need rewarded video — send [16] here.[1,3]
minbitrateintegerMinimum bit rate in Kbps. Exchange may set this dynamically or universally across publishers.128
maxbitrateintegerMaximum bit rate in Kbps. Exchange may set this dynamically or universally across publishers.512
playbackmethodinteger arrayAllowed playback methods. If none specified, assume all are allowed.[1,2,3,4]
deliveryinteger arraySupported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported.[1,2]
posintegerAd position on screen.[3]
companiodadobject arrayArray of banner objects if companion ads are available.(empty)
apiinteger arraySupported API frameworks. If not listed, assumed unsupported.[1,2,3,4,5]
companiontypeinteger arraySupported VAST companion ad types. Recommended if companion Banner objects are included.[1]

App Object

AttributeTypeDescriptionExample
idstringExchange-specific app ID."102938"
namestringApp name (may be aliased at the publisher’s request)."TestApp"
bundlestringApplication 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"
domainstringDomain of the app."game.app.com"
storeurlstringApp store URL for an installed app; for QAG 1.5 compliance.https://itunes.apple.com/us/app/somerandomapp/id1191231238?mt=8
catstring arrayArray of IAB content categories of the app.["IAB2-1", "IAB2-4"]
sectioncatstring arrayArray of IAB content categories that describe the current section of the app.["IAB2"]
pagecatstring arrayArray of IAB content categories that describe the current page or view of the app.["IAB2-1"]
verstringApplication version."1.0.3"
privacypolicyintegerIndicates if the app has a privacy policy, where 0 = no, 1 = yes.1
paidinteger0 = app is free, 1 = the app is a paid version.1
publisherobjectDetails about the Publisher of the app.(empty)
keywordsstringComma separated list of keywords about the app."automotive"
extobjectPlaceholder 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

AttributeTypeDescriptionExample
uastringBrowser 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"
geoobjectLocation of the device assumed to be the user’s current location defined by a Geo object.(empty)
dntinteger"Do Not Track" flag: 0 = unrestricted, 1 = do not track.0
lmtinteger"Limit Ad Tracking" flag: 0 = unrestricted, 1 = limited per commercial guidelines.1
ipstringIPv4 address closest to device."23.227.207.23"
ipv6stringIPv6 address closest to device.(empty)
devicetypeintegerThe general type of device.4
makestringDevice make."Apple"
modelstringDevice model."iPhone"
osstringDevice operating system."iOS"
osvstringDevice operating system version."10.1.3"
hmwstringHardware version of the device."5S"
hintegerPhysical height of the screen in pixels.568
wintegerPhysical width of the screen in pixels.320
ppiintegerScreen size in pixels per linear inch.326
pxratiofloatRatio of physical pixels to device-independent pixels.2
jsintegerSupport for JavaScript: 0 = no, 1 = yes.1
languagestringBrowser language using ISO-639-1-alpha-2."en"
carrierstringCarrier or ISP (e.g., "VERIZON"). "WIFI" is used to indicate high bandwidth.(empty)
connectiontypeintegerNetwork connection type.2
ifastringID sanctioned for advertiser use in the clear (i.e., not hashed).382A78A3-7EA0-4D3B-9724-0231C07D0C5A
didsha1stringHardware device ID (e.g., IMEI), hashed via SHA1.9db9123123b7fe382df2efeeb0176d2216cff7e
didmd5stringHardware device ID (e.g., IMEI), hashed via MD5.12f2f79bb5b7fe382df2efeeb0176da2216cff7e
dpidsha1stringPlatform device ID (e.g., Android ID), hashed via SHA1.a12f1479bb5b7fe382df2efeeb0176d16cff7e
dpidmd5stringPlatform device ID (e.g., Android ID), hashed via MD5.12sff9bb5b7fe382df2efeeb0176d2216cff7e
macsha1stringMAC address of the device, hashed via SHA1.12sff9bb5b7fe382df2efeeb0176d2216cff7e
macmd5stringMAC address of the device, hashed via MD5.12sff9bb5b7fe382df2efeeb0176d2216cff7e
extobjectPlaceholder for exchange-specific extensions. BidMachine sends info about battery state and rooted flag.{"battery": -100, "rooted": "false"}

User Object

AttributeTypeDescriptionExample
idstringExchange-specific ID for the user. At least one of id or buyerid is recommended."1"
buyeridstringBuyer-specific ID for the user as mapped by the exchange for the buyer. At least one of buyerid or id is recommended."1"
yobintegerYear of birth as a 4-digit integer.1984
genderstringGender, where "M" = male, "F" = female, "O" = other. (Omitted means unknown)"O"
keywordsstringComma-separated list of keywords, interests, or intent."game"
geoobjectLocation of the user’s home base defined by a Geo object. This is not necessarily their current location.(empty)
dataobject arrayAdditional user data. Each Data object represents a different data source.(empty)
extobject arrayPlaceholder for exchange-specific extensions to OpenRTB.{"consent" : "1"}

Data Object

AttributeTypeDescriptionExample
idstringExchange-specific ID for the data provider."2"
namestringExchange-specific name for the data provider."test"
segmentobject arrayArray of Segment objects that contain the actual data values.(empty)

Segment Object

AttributeTypeDescriptionExample
idstringID of the data segment specific to the data provider."12"
namestringName of the data segment specific to the data provider."address"
valuestringString representation of the data segment value."Delaware, Wilmington, 19809, United States"

Geo Object

AttributeTypeDescriptionExample
latfloatLatitude from -90.0 to +90.0, where negative is south.15
lonfloatLongitude from -180.0 to +180.0, where negative is west.30
typeintegerSource of location data; recommended when passing lat/lon.2
countrystringCountry code using ISO-3166-1-alpha-3"USA"
regionstringRegion code using ISO-3166-2; 2-letter state code if USA."US"
citystringCity using United Nations Code for Trade & Transport Locations. See Appendix A for a link to the codes."New York"
zipstringZip or postal code."19809"
utcoffsetintegerLocal time as the number +/- of minutes from UTC.180

Publisher Object

AttributeTypeDescriptionExample
idstringExchange-specific publisher ID."12"
namestringPublisher name (may be aliased at the publisher’s request)."test_name"
catstring arrayArray of IAB content categories that describe the publisher.["IAB2-1"]
domainstringHighest level domain of the publisher."publisher.com"

GDPR

ParameterTypeValuesExample Values
regs.ext.gdprinteger0: GDPR does not apply to this traffic 1: GDPR applies to this traffic0
user.ext.consentstringConsent string per IAB TCF spec. Also supports:
"0": consent NOT given
"1": consent given
"BOJObISOJObISAABAAENAA4AAAAAoAAA"

Regs

AttributeTypeDescriptionExample
coppaintegerFlag indicating if this request is subject to COPPA regulations (USA FTC), where 0 = no, 1 = yes.1
extobjectExtension for GDPR information.{ "gdpr": 0 }

Source Object

AttributeTypeDescriptionExample
fdintEntity responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source.1
tidstringTransaction ID that must be common across all participants in this bid request (e.g., potentially multiple exchanges).6ba06f9a-44c8-497d
pchainstringPayment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0.7tury102i-7uf7
extobjectPlaceholder 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

AttributeTypeDescriptionExample
ext.schainobjectThis 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

AttributeTypeDescriptionExample
completeintegerFlag 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
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. In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request.(empty)
verstringVersion of the supply chain specification in use, in the format of "major.minor" (e.g., "1.0")."1.0"
extobjectPlaceholder for advertising-system specific extensions to this object.(empty)

Nodes Object Properties

AttributeTypeDescription
asistringThe 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.
sidstringIdentifier 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.
ridstringThe request.id as issued by this seller.
namestringLegal company name paid for inventory. Should be omitted if listed in sellers.json. (optional)
domainstringBusiness domain of the represented entity. Should be omitted if listed in sellers.json. (optional)
hpintegerIndicates 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.
extobjectPlaceholder 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

NameTypeDescriptionExample
request.context.user.ext.impdepthuint32The count of impressions for a specific placement type in a given app session. Deprecated in 3.0.05
request.context.user.ext.sessiondurationuint64The total duration of time a user has spent so far in a specific app session expressed in seconds.55
request.context.user.ext.lastbundlestringThe 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.lastadomainstringThe 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.clickratefloatThe 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.05
request.context.user.ext.lastclickboolIndicates if the user clicked on the last impression, where 1 = clicked, 0 = didn’t click. Deprecated in 3.0.01
request.context.user.ext.completionratefloatPercentage of completions/impressions per user for a given number of impressions, where 70 represents 70% completion. Deprecated in 3.0.070

Device Contextual Data

NameTypeDescriptionExample
request.context.device.ext.inputlanguagelist[string]List of user languages.["DE", "US"]
request.context.device.ext.diskspacedoubleValue of available free disk space.61347.0
request.context.device.ext.totaldiskdoubleValue of total disk space.112221.0
request.context.device.ext.ringmuteboolDevice sound setting at ad request time.1 - yes, 0 - no
request.context.device.ext.chargingboolIs the device charging.1 - yes, 0 - no
request.context.device.ext.batterylevelfloatBattery level. 1 - full charge, 0.1 - 10%, 0 - empty.
request.context.device.ext.batterysaverboolBattery saver enabled.1 - yes, 0 - no
request.context.device.ext.darkmodeboolDark mode enabled.1 - yes, 0 - no
request.context.device.ext.airplanebool(Android only) Airplane mode enabled.1 - yes, 0 - no
request.context.device.ext.dndbool(Android only) "Do Not Disturb" setting enabled.1 - yes, 0 - no
request.context.device.ext.devicenamestringUser-defined name of the device.iPhone 14 Pro
request.context.device.ext.timeuint64POSIX timestamp, depends on device settings.1680197719.5890589
request.context.device.ext.headsetboolIs a wired headset connected.1 - yes, 0 - no
request.context.device.ext.headsetnamestringIdentifier of connected wireless headset."Headset"
request.context.device.ext.screenbrightdoubleBrightness level of screen from 0.0 to 1.0.0...1
request.context.device.ext.jailbreakboolIs the device jailbroken.1 - yes, 0 - no
request.context.device.ext.lastbootupuint64Android: ms since boot incl. sleep. iOS: POSIX timestamp of last boot.1676623341.589673
request.context.device.ext.totalmemuint64Total RAM in bytes.34359738368 B
request.context.device.ext.attsint(iOS only) App tracking authorization status: 0 - Not Determined, 1 - Restricted, 2 - Denied, 3 - Authorized.

App Contextual Data

NameTypeDescriptionExample
request.context.app.ext.install_timeuint64Unix timestamp in milliseconds of the application install (might be zero). Available since SDK 3.0.10.0
request.context.app.ext.first_launch_timeuint64Unix 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 version1.725296223359E12
request.context.app.ext.min_api_leveluint32(Android only) Minimal supported Android SDK version.21
request.context.app.ext.kotlin_versionstringKotlin runtime version.1.8.20