Bid Requests

BidRequest provides various forms of information to assist bidders in making targeting and pricing decisions. The following table summarizes the objects in the Bid Request model:

Bid Object Hierarchy

Object  

Description  

BidRequest  

Top-level object.  

Source  

Request source details on post-auction decisioning (e.g., header bidding).  

Regs  

Regulatory conditions are in effect for all impressions in this bid request, such as COPPA, GDPR, and so on.

Imp  

Container for the description of a specific impression; at least 1 per request.  

Banner  

Details for a banner impression (incl. in-banner video) or video companion ad.  

Video  

Details for a video impression.  

Native  

Container for a native impression conforming to the Dynamic Native Ads API.  

Format  

An allowed size of a banner.  

Pmp  

Collection of the private marketplace (PMP) deals applicable to this impression.  

Deal  

Deal terms about this impression between a seller and buyer.  

Site  

Details of the website calling for the impression (applicable to Mobile Web Inventory) 

App  

Details of the application calling for the impression (applicable to In-app Inventory) 

Publisher  

The entity that controls the content of and distributes the site or app.  

Content  

Details about the published content itself, within which the ad will be shown.  

Device  

Details of the device on which the content and impressions are displayed.  

Geo  

Location of the device or user’s home base depends on the parent object.  

User  

The Human user of the device; the audience for advertising.  

Object-Bid Request

Attribute 

Type 

Description 

id 

string 

Unique ID of the bid request, provided by the exchange. 

imp 

object array 

  

The array of Imp objects represents the impressions offered. At least one Imp object will be present. 

site 

object; conditional 

  

Details via a Site object about the publisher’s website. Only applicable for mobile web traffic. 

app 

object; conditional 

Details via an App object about the publisher’s app (i.e., non-browser applications). Only applicable for in-app traffic. 

device 

object 

  

Details via a Device object about the user’s device to which the impression will be delivered. 

user 

object 

  

Details via a User object about the human user of the device, the advertising audience. 

at 

integer 

Auction type, where 1 = First Price, 2 = Second Price 

tmax 

integer; conditional 

Maximum time (in milliseconds) the exchange allows for bids to be received, including Internet latency to avoid timeout. This value supersedes any a priori guidance from the exchange. 

cur 

string array 

  

An array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Default: USD 

bcat 

string array; conditional 

Blocked advertiser categories using the IAB content categories.  

badv 

string array; conditional 

Blocklist advertisers by their domains. 

source 

object; conditional 

A Source object (Object: Source) that provides data about the inventory source and which entity makes the final decision. 

regs 

object 

A Regs object (Object: Regs) that specifies any industry, legal, or governmental regulations in force for this request. 

Object-Source

Attribute 

Type 

Description 

fd 

integer 

Entity responsible for the final impression sale decision, where 

0 = exchange, 1 = upstream source. 

tid 

string 

Transaction ID that must be common across all participants in this bid request (e.g., potentially multiple exchanges). 

pchain 

string 

Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0. 

Object: Source Extension

Attribute 

Type 

Description 

schain object The SupplyChain Object, otherwise known as schain, is a part of an OpenRTB bid request and consists of "nodes." Each node in the schain object represents a specific entity participating in the bid request, which includes all entities involved in the direct flow of payment for inventory.
ext object; optional Placeholder for advertising-system-specific extensions to this object.
omidpn string Identifier of the OM SDK integration. This is the same as the "name" parameter of the OMID Partner object.
omidpv string The version of the OM SDK integration. This is the same as the "versionString" parameter of the OMID Partner object.

Object: Schain

Attribute 

Type 

Description 

complete 

integer; required 

Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or another medium of the inventory, where 0 = no, 1 = yes.

nodes  

object array; required  

The 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, i.e., the site's owner, app, or another medium. In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request.

ver string; required The version of the supply chain specification in use, in the format of “major.minor”. For example, for version 1.0 of the spec, use the string “1.0”.

Object: Nodes

Attribute 

Type 

Description 

asi string; optional The canonical domain name of the SSP, Exchange, Header Wrapper, etc system that bidders connect to. This may be the operational domain of the system, if that is different than the parent corporate domain, to facilitate WHOIS and reverse IP lookups to establish clear ownership of the delegate system. This should be the same value as used to identify sellers in an ads.txt file if one exists.
sid string; required The identifier is associated with the seller or reseller account within the advertising system. This must contain the same value used in transactions (i.e. OpenRTB bid requests) in the field specified by the SSP/exchange. Typically, in OpenRTB, this is publisher.id. For OpenDirect it is typically the publisher’s organization ID. Should be limited to 64 characters in length.
hp integer; required Indicates whether this node will be involved in the flow of payment for the inventory. When set to 1, the advertising system in the asi field pays the seller in the sid field, who is responsible for paying the previous node in the chain. When set to 0, this node is not involved in the flow of payment for the inventory.

Object-Regs

This object contains any legal, governmental, or industry regulations that apply to the request. The COPPA flag signals whether or not the request falls under the United States Federal Trade Commission’s regulations for the United States Children’s Online Privacy Protection Act (“COPPA”). The United States Federal Trade Commission has changed the Children’s Online Privacy Protection Act (“COPPA”), effective July 1, 2013. The proposal affects websites and associated services) that have been identified as (1) directed to users under 13 years of age; or (2) collecting information from users known to be under 13 (collectively “Children’s Sites”).

General Data Protection Regulation (GDPR) came into effect across the European Union on May 25, 2018. These new regulations create a framework to protect personal data about individuals in the EU, and all businesses who collect or process such data must adhere to it. Failure to comply with GDPR can result in strict penalties for non-compliant companies. GDPR requires parental consent to process the personal data of children under 16. InMobi will also reuse the COPPA flag designed for the US to indicate the GDPR age-gating criteria. Buyers must also continue to use the same COPPA flag for the EU region.

Attribute 

Type 

Description 

coppa 

integer 

Flag indicating if this request is subject to the COPPA regulations established by the USA FTC and GDPR age gating requirement, where 0 = no, 1 = yes. 

ext  

Object  

For more information on extension parameters, see Objects: Regs Extension.

Object: Regs Extension

Attribute 

Type 

Description 

gdpr 

integer 

Whether or not the request is subject to GDPR regulations - 0 =No, 1 = Yes - omission indicates Unknown 

Object-Imp

Attribute 

Type 

Description 

id 

String; required 

A unique identifier for this impression within the context of the bid request (starts with 1 and increments). 

banner 

object 

  

A Banner object; present if this impression is offered as a banner ad opportunity. 

video 

object 

  

A Video object; present if this impression is offered as a video ad opportunity. 

native 

object 

  

A Native object; present if this impression is offered as a native ad opportunity. 

pmp 

object 

A PMP object containing any private marketplace deals in effect for this impression. 

displaymanager 

string 

Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). 

instl 

integer; default 0 

1 = the ad is interstitial or full screen, 0 = not interstitial. 

bidfloor 

double 

The minimum bid for this impression is expressed in CPM. 

bidfloorcur  

 

string; default USD 

 

Currency specified using ISO-4217 alpha codes.  

 

secure 

intege

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. 

ext 

object 

For more information on extension parameters, see Object: Imp Extension.

displaymanagerver string Indicates the integration version of the value indicated in the displaymanager.

Object: Imp Extension

The InMobi RTB platform is directly integrated with multiple MRC-accredited viewability tracking vendors to better serve brand advertisers. This feature is not enabled for bidders by default.

Attribute 

Type 

Description 

viewabilityvendors 

string array; optional 

Supported viewability vendor SDKs in-app for all ad-formats for this impression. For more information, see Viewability Vendors. Example: ["integralads.com","moat.com", "company.com-omid"] 

Object-Banner

Attribute 

Type 

Description 

 w 

integer 

Width in device independent pixels 

 h 

integer 

Height in device independent pixels 

 battr 

integer array; optional 

Blocked creative attributes. For more information, see Creative Attributes.

 pos 

integer; optional 

Ad position on the screen. For more information, see Ad Position.

 api 

integer array; optional 

List of supported API frameworks for this impression. For more information, see API Frameworks. If an API is not explicitly listed, it is assumed not to be supported. 

 id 

string; optional 

Unique identifier for this banner object. Values start at 1 and increase with each object; and will be unique within an impression. 

Object-Format

Attribute 

Type 

Description 

w 

integer 

Width in device-independent pixels. 

h 

integer 

Height in device-independent pixels. 

wratio 

integer 

Relative width when expressing size as a ratio.  

hratio 

integer 

Relative height when expressing size as a ratio.  

wmin 

integer 

The minimum width in device-independent pixels at which the ad will be displayed the size is expressed as a ratio. 

Object-Native

Attribute 

Type 

Description 

request 

object 

Request payload complying with the Native Ad Specification. 

ver 

string 

A version of the Native Ad Specification to which the request complies. 

api 

integer array; optional 

List of supported API frameworks for this impression. For more information, see API Frameworks. If an API is not explicitly listed, it is assumed not to be supported. 

battr 

integer array; optional 

Blocked creative attributes. For more information, see Creative Attributes.

plcmttype Integer The design/format/layout of the ad unit being offered.

Object: Native Markup Request

Attribute 

Type 

Description 

ver 

string 

A version of the Native Markup version in use. 

layout 

integer 

The Layout ID of the native ad unit. See the table of Native Layout IDs in Video Experiences.

plcmtcnt 

integer; default 1 

The number of identical placements in this layout. 

assets 

object array 

An array of Asset Objects. Any bid must comply with the array of elements expressed here. 

seq 

Integer 

0 for the first ad, 1 for the second ad, and so on. This is not the sequence number of the content in the stream. 

Object: Native Asset

Attribute 

Type 

Description 

id 

integer 

Unique asset ID. Denotes the counter for the array. 

required 

integer 

Set to 1 if the asset is required (The InMobi RTB Platform will not accept a bid without it) 

title 

object 

Title object for title assets. See Object: Title definition below. 

img 

object 

Image object for image assets. See Object: Image definition below. 

data 

object 

Data object for ratings, prices, and so on. See the Data Object definition below. 

Object: Title

Attribute 

Type 

Description 

len 

integer 

The maximum length of the text in the title element. 

Object: Image

Attribute 

Type 

Description 

type 

integer 

Type ID of the image element supported by the publisher. The publisher can display this information in an appropriate format. See Image Asset Type Table for commonly used examples. 

wmin 

integer 

The minimum requested width of the image is in pixels. 

hmin 

integer 

The minimum requested height of the image is in pixels. 

w 

integer 

Width in device independent pixels 

h 

integer 

Height in device independent pixels 

Image Asset Types

Type ID 

Name 

Description 

1 

Icon 

Icon Image 

2 

Logo 

Logo image for the brand/app. 

3 

Main 

Large image preview for the ad. 

Object: Data

Attribute 

Type 

Description 

type 

integer 

Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format. For commonly used examples, see Data Asset types. 

len 

integer; optional 

The maximum length of the text in the element’s response. 

Data Asset Types

Type ID 

Name 

Format 

Description 

1 Sponsored text Sponsored By message where response should contain the brand name of the sponsor.

2 

desc 

text 

Descriptive text associated with the product or service being advertised. 

3 

rating 

number formatted as string 

Rating of the product being offered to the user. For example an app’s rating in an app store from 0-5. 

5 

downloads 

number formatted as string 

Number downloads/installs of this product. 

12 

cta_text 

text 

CTA description - descriptive text describing a ‘call to action’ button for the destination URL. 

Object-Video

InMobi RTB platform support videos that comply with the VAST standard. Companion ads are supported and are recommended. The InMobi RTB platform will signal this by including an array of Banner objects under companion ads.

Attribute 

Type 

Description 

mimes 

string array 

Supported MIME types include "video/mp4", “video/3gpp”. 

minduration 

integer; optional 

Minimum video ad duration in seconds. 

maxduration 

integer 

Maximum video ad duration in seconds. The currently supported max duration is 30 seconds. 

protocols 

integer array 

An array of supported video protocols. For more information, see Protocols.

w 

integer  

Width of the video player in device-independent pixels (DIPS). 

h 

integer 

Height of the video player in device-independent pixels (DIPS). 

startdelay 

integer 

Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. For more information, see Start Delay.

placement 

integer 

Placement type for impression. For more information, see Video Placement Types.

linearity 

integer 

Indicates if the impression must be linear, nonlinear, etc. If none is specified, assume all are allowed. For more information, see Video Linearity.

skip 

  

integer 

Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. 

skipmin 

integer 

Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable. 

skipafter 

integer 

The number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable. 

battr 

integer array; optional 

Blocked creative attributes. For more information, see Creative Attributes.

maxbitrate 

integer 

Maximum bitrate in Kbps. 

boxingallowed 

  

integer; optional 

Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes. 

playbackmethod 

  

integer array; optional 

Playback methods that may be in use. If none are specified, any method may be used. For more information, see Playback Methods.

playbackend 

integer; optional 

The event that causes playback to end. For more information, see Playback Cessation Modes. 

pos 

integer 

Ad position on the screen. For more information, see Ad Position.

companionad 

  

object array; optional 

An array of Banner objects (Object: Banner) if companion ads are available. 

api 

  

integer array; optional 

List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported. 

companiontype 

integer array 

Supported VAST companion ad types. For more information, see Companion Types.

ext 

object 

See Extensions: Video.

 Here’s a brief guide to various types of video requests:

Full screen video, including landscape, portrait, vertical experiences 

  • bidrequest.imp.instl = 1 

  • bidrequest.imp.video.placement = 5 (denoting Interstitial/Slider/Floating) 

  • bidrequest.imp.video.ext.experiences = [1,2,3] (for more information, see Video Experiences for video experience id mappings. Experiences absent in the experiences array can be assumed not to be supported. It is mandatory to explicitly call out the experience used/required in the response for portrait/vertical videos to function correctly. 

In-feed video 

  • bidrequest.imp.instl = 0 

  • bidrequest.imp.video.placement = 4 (denoting In-Feed)

Extensions: Video

Value 

Type 

Description 

rewarded 

boolean 

Denotes if the site is a rewarded video site. 

experiences 

integer array 

List of video experiences supported. For more information, see Video Experiences

Object-PMP

Attribute 

Type 

Description 

deals 

object array 

An array of Deal objects convey the specific deals applicable to this impression. 

Object-Deal

Attribute 

Type 

Description 

id 

string 

A unique identifier for the direct deal. 

bidfloor 

double 

The minimum bid for this deal is expressed in CPM. 

wseat 

string array 

Whitelist of buyer seats (e.g., advertisers, agencies) was allowed to bid on this deal. IDs of seats and the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. Omission implies no seat restrictions.

Object-Site

Attribute 

Type 

Description 

id 

string 

Exchange-specific site ID 

name 

string; optional 

Site name (maybe aliased at the publisher’s request). 

domain 

string; optional 

The domain of the site (e.g., “mysite.foo.com”). 

cat 

string array; optional 

An array of IAB content categories of the site. 

page 

string; optional 

URL of the page where the impression will be shown 

publisher 

object 

For more information, see Object: Publisher.

mobile 

integer; default 1 

Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes. 

Object-App

Attribute 

Type 

Description 

id 

string 

Exchange-specific app ID. 

name 

string 

App name 

bundle 

string 

A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name. On iOS, it is a numeric ID. 

domain 

 string; optional 

The domain of the app 

storeurl 

string; optional 

App store URL for an installed ap

publisher 

object 

For more information, see Object: Publisher.

content 

object  

For more information, see Object: Content.

cat 

string array; optional 

An array of IAB content categories of the app. 

Object: Content

Attribute 

Type 

Description 

id 

string  

ID uniquely identifying the content. 

title 

string 

Content title. 
Video Examples: “Search Committee” (television), “A New 

Hope” (movie), or “Endgame” (made for web). 

Non-Video Example: “Why an Antarctic Glacier Is Melting So 

Quickly” (Time magazine article). 

 

series 

string 

Content series. 

Video Examples: “The Office” (television), “Star Wars” (movie), 

or “Arby ‘N’ The Chief” (made for web). 

Non-Video Example: “Ecocentric” (Time Magazine blog) 

 

artist 

string 

Artist credited with the content. 

genre 

string 

A genre that best describes the content (e.g., rock, pop, etc). 

cat 

string array 

Array of IAB content categories that describe the content 

producer 

context 

integer 

Type of content (game, video, text, etc.).  

contentrating 

string 

Content rating (e.g., MPAA). 

userrating 

string 

User rating of the content  

livestream 

integer 

0 = not live, 1 = content is live  

len 

integer 

Length of content in seconds; appropriate for video or audio. 

Object: Publisher

Attribute 

Type 

Description 

id 

string 

Exchange-specific publisher ID 

name 

string 

Publisher name 

cat 

string arra

An array of IAB content categories that describe the publisher 

domain 

string 

The highest level domain of the publisher 

Object-Device

Attribute 

Type 

Description 

ua 

string 

Browser user agent string. 

geo 

object 

The location of the device is assumed to be the user’s current location defined by a Geo object. 

dnt 

integer; optional 

Standard “Do Not Track” flag as a set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track. 
 
Applicable for Mobile Web traffic. 

lmt 

integer; optional 

“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines. 

 

Applicable for In-App traffic. 

ip 

string; optional 

IPv4 address closest to device. 

devicetype 

integer 

The general type of device.For more information, see Device Type.

make 

string; optional 

Device make (e.g., “Apple”). 

model 

string; optional 

Device model (e.g., “iPhone”). 

os 

string 

Device operating system (e.g., “iOS”) 

osv 

string 

Device operating system version (e.g., “3.1.2”). 

hvw 

string 

Hardware version of the device (e.g., “5S” for iPhone 5S). 

language 

string; optional 

Browser language using ISO-639-1-alpha-2. 

carrier 

string; optional 

Carrier or ISP (e.g., “VERIZON”). “WIFI” is often used in mobile to indicate high bandwidth (e.g., video-friendly vs. cellular). 

connectiontype 

integer 

Network connection type. For more information, see Connection Type.

ifa 

string; optional 

ID sanctioned for advertiser use in the clear (i.e., not hashed). 

Object-Geo

Attribute 

Type 

Description 

lat 

float 

Latitude from -90.0 to +90.0, where negative is south. 

lon 

float 

Longitude from -180.0 to +180.0, where negative is west. 

type 

integer 

Source of location data; recommended when passing lat/lon. For more information, see Location Type.

country 

string 

Country code using ISO-3166-1-alpha-3. 

city 

string; optional 

InMobi RTB Platform derived city name. 

zip 

string; optional 

Zip or postal code. 

Object-User

Attribute 

Type 

Description 

id 

string; recommended 

Exchange-specific ID for the user. At least one of id or buyer's id is recommended. 

buyeruid 

string; recommended 

Buyer-specific ID for the user as mapped by the exchange for the buyer. At least one of the buyer's IDs is recommended. 

gender 

string; optional 

Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown). 

customdata 

string 

Optional feature to pass bidder data that was set in the exchange’s cookie. The string must be in base85 cookie-safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. 

geo 

object 

The location of the user’s home base is defined by a Geo object. For more information, see Object: Geo.

data 

object array; optional 

Additional user data. For more information, see Object: Data.

represents a different data source. 

ext 

object 

See Extension: User.

OBJECT: Extended Identifier (User.ext.eids)

Parameter 

Scope 

Type 

Description 

source 

recommended 

string 

Cookie or platform-native identifier. 

uids 

 recommended 

object array 

An array of extended ID UID objects from the given source. 

Extension: User

Attribute 

Type 

Description 

consent 

string 

User consent when GDPR regulations are in effect - an optional string that contains the data structure developed by the GDPR Consent Working Group under the auspices of IAB Europe.  

 

0 = No, 1 = Yes - omission indicates Unknown 

providersSettings 

Object  

See Extension: consented_providers_settings.

Extension: consented_providers_settings

Attribute 

Type 

Description 

consented_providers 

Integer List 

List of consent providers to give enhanced transparency and choice to consumers while providing enhanced control to publishers.  

Object: Geo

Attribute 

Type 

Description 

lat 

Float; optional 

Latitude from -90.0 to +90.0, where negative is south. 

lon 

Float; optional 

Longitude from -180.0 to +180.0, where negative is west. 

country 

string; optional 

Source of location data; recommended when passing 

lat/lon.  

 

city 

string; optional 

City using United Nations Code for Trade & Transport 

Locations. 

zip 

string; optional 

Zip or postal code. 

type 

integer 

Source of location data; recommended when passing 

lat/lon. For more information, see Location Type.

 

On This Page

Last Updated on: 17 Nov, 2022