Bid Request Specification

The following page describes the fields of the BidRequest object:

Request

Attribute	Type	Description	Example
id	optional, string	Unique ID of the bid request, provided by the exchange.	d5260eec-75d9-4f7d-86bc-22b01b4c779e
imp	required, object[]	Array of Imp objects representing the impressions offered. Must contain at least one item.	(array of Imp objects)
app	required, object	Details about the publisher’s app (non-browser applications). Recommended for in-app traffic.	(App object)
device	required, object	Details about the user’s device to which the impression will be delivered.	(Device object)
user	required, object	Details about the human user of the device (the advertising audience).	(User object)
test	optional, integer (default 0)	Test mode flag: 0 = live mode, 1 = test mode (non-billable).	0
at	optional, integer (default 2)	Auction type: 1 = First-Price, 2 = Second-Price Plus (BidMachine supports only 2).	2
cur	optional, string[] (default ["USD"])	Array of allowed currencies (ISO-4217 codes). Recommended if multiple currencies are supported. Default is ["USD"].	['USD']
bcat	optional, string[]	Blocked advertiser categories using the IAB content taxonomy.	['IAB2-1']
badv	optional, string[]	Block list of advertiser domains.	['blocked.domain']
regs	optional, object	Regs object specifying industry, legal, or governmental regulations for this request.	(Regs object)

Imp Object

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 a UUID).	6ba06f9a-44c8-497d-8bc3-78804bebc2c8
banner	object	Banner object; required if this impression is offered as a banner ad opportunity.	(Banner object)
video	object	Video object; required if this impression is offered as a video ad opportunity.	(Video object)
native	object	Native object; required if this impression is offered as a native ad opportunity.	(Native object)
displaymanager	required, string	Name of ad mediation partner, SDK technology, or player responsible for rendering the ad. Recommended for video and in-app SDKs.	you_ssp_name
displaymanagerver	required, string	Version of the ad mediation partner or SDK. Recommended for video and in-app SDKs.	2.0.0
instl	optional, integer (default 0)	1 = interstitial/fullscreen, 0 = banner.	0
tagid	optional, string	Identifier for the ad placement or tag used to initiate the auction. Useful for debugging and optimization.	my__debug__tag
bidfloor	required, number (default 0)	Minimum bid for this impression expressed in CPM.	0.15
bidfloorcur	optional, string (default "USD")	Currency for the bidfloor (ISO-4217). May differ from bid response currency if allowed.	USD

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 with w, then w is treated as preferred width.	320
hmax	integer	Maximum height of the impression in pixels. If included with h, then h is treated as preferred height.	50
wmin	integer	Minimum width of the impression in pixels. If included with w, then w is treated as preferred width.	320
hmin	integer	Minimum height of the impression in pixels. If included with h, then h is treated as preferred height.	50
id	string	Unique identifier for this banner object. Recommended for companion ads; values unique within an impression.	ap1gm-0jioruind-1ffopjgo1p
btype	integer[]	Blocked banner ad types.	[2]
battr	integer[]	Blocked creative attributes. Appodeal currently blocks: Expandable (User Initiated – Rollover), Pop (Over/Under/Exit), Suggestive Imagery, Shaky/Flashing/Animated, Windows Dialog Style.	[5,8,9,10,14]
pos	integer	Ad position on screen.	5
mimes	string[]	Supported MIME types (e.g., image/png, image/jpg, image/gif).	['image/jpg','image/gif','image/png']
topframe	integer	Top-frame flag: 0 = no, 1 = yes.	1
api	integer[]	List of supported API frameworks. Unlisted APIs are assumed unsupported.	[5,3]

Video Object

Attribute	Type	Description	Example
mimes	string[]	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 protocols when possible). At least one must be specified in protocol or protocols.	1
protocols	integer[]	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	Start delay in seconds for pre-roll, mid-roll, or post-roll ad placements.	1
linearity	integer	Impression linearity: 1 = linear, 2 = non-linear. If unspecified, assume all allowed.	1
battr	integer[]	Blocked creative attributes. IMPORTANT: for rewarded video, send [16] here.	[1,3]
minbitrate	integer	Minimum bit rate in Kbps.	128
maxbitrate	integer	Maximum bit rate in Kbps.	512
playbackmethod	integer[]	Allowed playback methods. If none specified, assume all are allowed.	[1,2,3,4]
delivery	integer[]	Supported delivery methods (e.g., streaming, progressive). If none specified, assume all supported.	[1,2]
pos	integer	Ad position on screen.	3
companiodad	object[]	Companion banner objects (if companion ads are available).	(empty)
api	integer[]	Supported API frameworks. Unlisted APIs are assumed unsupported.	[1,2,3,4,5]
companiontype	integer[]	Supported VAST companion ad types. Recommended if companion banners are used.	[1]

Native Object

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 the request complies; recommended for efficient parsing.	"1.0"
api	integer[]	List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed unsupported.	[1]
battr	integer[]	Blocked creative attributes.	[5,3]

App Object

Attribute	Type	Description	Example
id	required, string	Exchange-specific app ID.	"102938"
name	required, string	App name (may be aliased at the publisher’s request).	"MyApp"
bundle	required, string	Application bundle or package name (e.g., com.app.game); intended to be a unique ID across exchanges. iOS passes the App Store ID, Android passes the package name.	Android: "com.appodeal.test", iOS: "78945611"
domain	optional, string	Domain of the app.	"game.app.com"
storeurl	optional, string	App store URL for an installed app; for QAG 1.5 compliance.	"https://itunes.apple.com/..id1234"
cat	optional, string[]	Array of IAB content categories of the app.	['IAB2-1', 'IAB2-4']
sectioncat	optional, string[]	Array of IAB content categories describing the current section of the app.	['IAB2']
pagecat	optional, string[]	Array of IAB content categories describing the current page or view of the app.	['IAB2-1']
ver	optional, string	Application version.	"1.0.3"
privacypolicy	optional, integer	Privacy policy flag: 0 = no, 1 = yes.	1
paid	optional, integer	App cost flag: 0 = free, 1 = paid.	1
publisher	optional, object	Details about the publisher of the app.	(empty)
keywords	optional, string	Comma-separated list of keywords about the app.	"automotive"
ext	optional, object	Placeholder for exchange-specific extensions to OpenRTB.	(empty)

Device Object

Attribute	Type	Description	Example
ua	optional, 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	required, object	Location of the device assumed to be the user’s current location defined by a Geo object.	(Geo object)
dnt	optional, integer	Standard “Do Not Track” flag: 0 = unrestricted, 1 = do not track.	0
lmt	optional, integer	“Limit Ad Tracking” signal: 0 = unrestricted, 1 = limited.	1
ip	optional, string	IPv4 address closest to device.	23.227.207.23
ipv6	optional, string	IPv6 address closest to device.	2001:0db8:11a3:09d7:1f34:8a2e:07a0:765d
devicetype	optional, integer	The general type of device.	4
make	optional, string	Device make.	"Apple"
model	optional, string	Device model.	"iPhone"
os	required, string	Device operating system.	"iOS"
osv	optional, string	Device operating system version.	"10.1.3"
hwv	required, string	Hardware version of the device.	"5S"
h	optional, integer	Physical height of the screen in pixels.	568
w	optional, integer	Physical width of the screen in pixels.	320
ppi	optional, integer	Screen size in pixels per linear inch.	326
pxratio	optional, float	Ratio of physical pixels to device-independent pixels.	2
js	optional, integer	Support for JavaScript: 0 = no, 1 = yes.	1
language	optional, string	Browser language (ISO-639-1-alpha-2).	"en"
carrier	optional, string	Carrier or ISP (e.g., “VERIZON”). “WIFI” indicates high bandwidth.	(empty)
connectiontype	optional, integer	Network connection type.	2
ifa	optional, string	ID sanctioned for advertiser use in the clear (not hashed).	382A78A3-7EA0-4D3B-9724-0231C07D0C5A

User Object

Attribute	Type	Description	Example
id	recommended, string	Exchange-specific ID for the user. At least one of id or buyerid is recommended.	"1"
yob	optional, integer	Year of birth as a 4-digit integer.	1984
gender	optional, string	Gender: "M" = male, "F" = female, "O" = other (omitted = unknown).	"O"
keywords	optional, string	Comma-separated list of keywords, interests, or intent.	"game"
geo	optional, object	Location of the user’s home base defined by a Geo object. Not necessarily their current location.	(Geo object)

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"
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

Regs Object

Attribute	Type	Description	Example
coppa	optional, integer	Flag indicating if this request is subject to COPPA regulations (USA FTC), where 0 = no, 1 = yes.	0
ext	optional, object	Ext object for GDPR in OpenRTB 2.2–2.5.	(see below)

Regs.ext:

Attribute	Type	Description	Example
gdpr	optional, integer	Signals if the request is subject to GDPR regulations: 0 = No, 1 = Yes.	0