List of supported OpenRTB bid request fields

id

String; required

The IX unique ID for the request (alphanumeric).

imp

Object; required

The Impression Object; contains at least one Banner Object or Video Object.

device

Object; required

The Device Object.

tmax

Object; required

Maximum time in milliseconds that IX allows to receive bids. To avoid timeouts, the tmax field does not subtract internet latency between IX and the DSP.

Note: If required, we can subtract latency when passing tmax. For more information, contact your IX Representative.

ext

Required

A custom IX Request Extension Object that contains additional information about the bid request.

app

Object; optional

The App Object; included if the impression originates from an application.

bcat

Array of Strings; optional

An array of blocked advertiser categories, based on standard IAB content categories. The full list is available in section 5.1 of the OpenRTB Specification (version 2.5).

badv

Array of strings; optional

A list of advertiser domains that have been blocked by the publisher from serving on their properties, for example “ford.com”.

regs

Object; optional

The Regulations Object.

site

Object; optional

The Site Object; included if the impression originates from a website.

user

Object; optional

The User Object.

pchain

String; optional

The Payment ID chain string provides visibility into an impression's supply path. For bid requests sourced directly from IX, the pchain field will display our TAG ID (50b1c356f2c5c8fc) and publisher ID (for example, 2167).

For example, 50b1c356f2c5c8fc:2167. For bid requests sourced from a supplier, the pchain field will display the TAG ID and publisher ID for both the supplier and IX.

For example, <Supplier ID>:<Publisher ID>-50b1c356f2c5c8fc:2167. For more information or to get a list of supplier IDs for pchain, contact TAG at info@tagtoday.net.

schain

Object; optional

Like pchain, schain also provides buyers visibility into all parties who are involved in the selling or reselling of a bid request.

To interpret the schain object, you can reference our sellers.json file that contains a list of all our supply partners at www.indexexchange.com/sellers.json.

omidpn

String; optional

An identifier for the OM SDK integration. This is the same as the name parameter of the OMID Partner object.

omidpv

String; optional

A version of the OM SDK integration. This is the same as the versionString parameter of the OMID Partner object.

complete

Integer; required

A flag that specifies whether the chain contains all nodes involved in the transaction leading back to the supply source of the inventory, where:

• 0 is No
• 1 is Yes

nodes

Object array; required

An array of SupplyChainNode objects in the order of the chain. Each node represents a different seller or exchange system that has touched the impression. The last node in the array represents the seller sending the bid request.

ver

String; required

Version of the supply chain specification in use, in the format of “major.minor”. IX is currently using version 1.0 of the spec.

asi

String; required

Domain name of the system that the bidder connects to. For example, SSP, exchange.

Note: You can find the sellers.json file for each node through this domain name. The same domain is also used in ads.txt files for publishers (for example, indexexchange.com).

pid

String; required

The seller or reseller account ID.

Note: Support for the pid field ended on Feb 21, 2020. You can find the same information from sid (see below) and site.publisher.id.

rid

String; optional

The request's OpenRTB RequestId issued by the seller.

Note: The same information can also be found in bidrequest.id.

String; required

The seller or reseller account ID.

Note: The same information can also be found in site.publisher.id.

hp

Integer; required

Specifies whether this node is involved in the flow of payment for the inventory. The hp field is sent if an upstream chain includes it. IX's node will always include hp=1. For version 1.0 of SupplyChain, this property should always be 1.

id

String; required

A unique identifier for this impression.

tagid

String; optional

A unique identifier for the ad placement or ad tag on a publisher's website that was used to initiate the auction. DSPs can use this detailed breakdown of publisher inventory indicating where the ad is located on a web page to optimize and troubleshoot buyer campaigns.

Note: We pass tagid on some traffic where possible.

banner

Object; required

The Banner Object.

Note: All requests must include at least one Banner Object or Video Object.

secure

Integer; required

Specifies whether impressions require secure HTTPS URL creative assets and markup, where:

• 0 specifies that secure assets are not required.
• 1 specifies that secure assets and markup are required.

video

Object; required

The Video Object.

Note: All requests must include at least one Video Object or Banner Object.

bidfloor

Float; optional

The minimum bid for this impression in CPM.

ext

Object; optional

instl

Integer; optional

Specifies whether an ad is interstitial, where:

• 0 specifies that the ad is not interstitial.
• 1 specifies that the ad is interstitial or full screen.

pmp

Object; optional

private_auction

Integer; optional

The scope of DSP bidding eligibility for this impression, where:

1 is Private (eligible bids are restricted to the deals specified).

deals

Array of Objects; optional

A collection of Direct Deals Objects containing any direct deals eligible for this impression.

ext

Object; optional

A custom IX PMP Extension Object that contains additional information about this deal.

id

String; required

A unique identifier for this direct deal.

at

Integer; optional

The auction type for this direct deal, where:

• 1 is a First Price auction
• 2 is a Second Price auction
• 3 is a Fixed Price auction

bidfloor

Integer (if sent as cents, like 134) or Float (if sent as dollars, like 1.34); optional

Designated floor price for this direct deal, in US (sent in cents, by default).

Note: It can be sent in dollars if requested, but the price in the response Bid Object must also be sent in dollars.

wseat

String; optional

A whitelist of buyer seats (for example, advertisers, agencies) that are allowed to bid on a deal.

name

String; optional

Placement name for all impressions operating in the private market (for example, "The Daily Times").

disc

Float

A number between 0.01 - 1.0 representing the discount negotiated between a publisher and buyer. This value is applied to the ${AUCTION_PRICE} win notification macro for winning impressions. IX supports one value past the decimal point on discounts (for example, 15.5%).

Example: A 25% discount is sent as disc = 0.25. For a $10.00 winning bid, the 25% discount is applied and passed as $7.50 in the ${AUCTION_PRICE} macro.

To learn more about discounts for deals, see Negotiating discounts on deals.

bcrid

Array of Strings; required

DSP Creative IDs that are blocked because they are pending review or have been blocked by IX and are therefore excluded from participating in an auction.

Note: The number of Creative IDs that display is configurable per DSP.

floor

Array of Integers; optional

An array of bid floor values, in cents.

Note: The array index identifies the bid floor of a seat with corresponding index in the wseat field of the Bid Request Object.

hb

Integer; optional

Specifies whether to use Header Tag inventory bid requests, where:

• 0 is a traditional ad tag request.
• 1 is a Header Tag ad request.

Note: This is not included by default and DSPs must request it.

wopv

String; optional

The White Ops MediaGuard lookupID. The lookupID present in the bid request indicates that MediaGuard has scanned the ad request and determined that it is not fraudulent. For more information about Invalid Traffic (IVT) monitoring, see Supply quality guidelines.

id

String; required

The IX-assigned unique numeric identifier for this app.

bundle

String; optional

The App name or bundle (for example, "com.foo.mygame"), used as a unique identifier across exchanges.

cat

Array of Strings; optional

The standard IAB content category for the overall site (for example, ["IAB3-7"]). Refer to the OpenRTB Specification (version 2.5) for a complete list.

content

Object; optional

The Content Object.

domain

Optional

A static value representing the domain of the app.

keywords

String; optional

A comma-separated list of keywords related to the app.

name

String; optional

The name of the app. It may be masked if requested by the publisher.

paid

Integer; optional

Specifies whether the app is a paid or free version, where:

• 0 specifies that the app is free
• 1 specifies that the app is a paid version

privacypolicy

Specifies whether the app has a privacy policy, where:

• 0 is no
• 1 is yes

publisher

Object; optional

The Publisher Object.

storeurl

String; optional

The App store URL for an installed app for QAG 1.5 compliance.

ver

String; optional

The application version.

h

Integer; required

The height of this impression, in pixels.

topframe

Boolean; required

Specifies whether the banner ad is delivered in the top frame or in an iFrame, where:

• 0 specifies that the ad is displayed in an iframe.
• 1 specifies that the ad will not be displayed in an iframe.

Note: Expandable ads must meet our expansion requirements.

w

Integer; required

The width of this impression, in pixels.

battr

Array; optional

Indicates blocked creative attributes; if blank, it is assumed that all types are allowed. Refer to the OpenRTB API Specification Version 2.5 for a full list of values.

btype

Integer; optional

The list of blocked creative types, where:

• 1 is an XHTML text ad
• 2 is an XHTML banner ad
• 3 is a JavaScript ad
• 4 is an iframe

If left blank, IX assumes that all types are allowed.

expdir

Array of Integers; optional

Indicates expandable ad direction.

api

Array of Integers; optional

Specifies the supported API frameworks, where:

• 1 is VPAID 1.0
• 2 is VPAID 2.0
• 3 is MRAID 1.0
• 4 is ORMMA
• 5 is MRAID 2.0
• 6 is MRAID 3.0
• 7 is OMID 1.0

By default, custom APIs are assumed as unsupported.

hmax

String; optional

The maximum height of the impression in pixels. If included, it specifies that a range of sizes is allowed with this maximum height and h is considered to be the recommended size. If it is not included, h is considered an exact requirement.

hmin

String; optional

The minimum height of the impression in pixels. If included, it specifies that a range of sizes is allowed with this minimum height and h is considered as the recommended size. If not included, h is considered an exact requirement.

id

String; optional

A unique identifier for this banner object; especially useful for tracking multiple Banner Objects (for example, in companion banner array). It usually begins with 1 and increases with each object.

mimes

Array of Strings; optional

Whitelist of content MIME types supported. Popular MIME types include, but are not limited toimage/jpg and image/gif.

pos

Integer; optional

Specifies the position of the ad as a relative measure of visibility or prominence where:

• 0 is unknown
• 1 is above the fold (default)
• 2 is deprecated (resolution dependent)
• 3 is below the fold
• 4 is header
• 5 is footer
• 6 is sidebar
• 7 is full-screen

wmax

Integer; optional

The maximum width of the impression in pixels. If included, it specifies that a range of sizes is allowed with this maximum width and w is considered to be the recommended size. If not included, w is considered an exact requirement.

wmin

Integer; optional

The minimum width of the impression in pixels. If included, it specifies that a range of sizes is allowed with this minimum width and w is considered as the recommended size. If not included, w is considered an exact requirement.

maxduration

Integer; required

Maximum video ad duration, in seconds.

minduration

Integer; required

Minimum video ad duration, in seconds.

mimes

Array of Strings; required

A list of supported video content MIME types. Popular MIME types supported by HTML5 players include:

• video/mp4
• video/webm
• video/ogg

For VPAID support, make sure to specify application/javascript.

protocols

Array of Integers; required

An array of supported video protocols. At least one supported protocol must be specified, where:

• 2 is VAST 2.0
• 3 is VAST 3.0
• 5 is VAST 2.0 Wrapper
• 6 is Vast 3.0 Wrapper

api

Array of Integers; optional

A list of supported API frameworks, where:

• 1 is VPAID 1.0
• 2 is VPAID 2.0
• 3 is MRAID-1
• 4 is ORMMA
• 5 is MRAID-2
• 7 is OMID-1

By default, custom APIs are assumed to be unsupported.

boxingallowed

Integer; optional

Specifies whether letter-boxing of 4:3 content into a 16:9 window is allowed, where:

• 0 specifies that boxing is not allowed
• 1 specifies that boxing is allowed (default setting)

battr

Array; optional

Specifies blocked creative attributes. If blank, it is assumed that all types are allowed.

companionad

Array of Objects; optional

Available companion ads are listed as an array of Banner Objects.

companiontype

Array of Integers; optional

A list of supported VAST companion ad types, where:

• 1 is a Static Resource
• 2 is an HTML Resource
• 3 is an iframe Resource

delivery

Array of Integers; optional

A list of supported delivery methods. If blank, it is assumed that all are supported, where:

• 1 is streaming
• 2 is progressive

ext

Object; optional

A custom IX Video Extension Object that contains additional information about this impression.

h

Integer; optional

The height of the player, in pixels.

linearity

Integer; optional

Specifies whether the ad impression is linear or non-linear. If the field is blank, the ad impression can be of any type, where:

• 1 is Linear/In-stream
• 2 is Non-Linear/Overlay

maxextended

The maximum extended ad duration if extension is allowed, where:

• If blank or 0, an extension is not allowed.
• If -1 , an extension is allowed and there is no time limit imposed.
• If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value.

maxbitrate

Integer; optional

The maximum bit rate in Kbps.

minbitrate

Integer; optional

The minimum bit rate in Kbps.

placement

Integer; optional

The video's placement type, where:

• 1 is In-Stream
• 2 is In-Banner
• 3 is In-Article
• 4 is In-Feed
• 5 is Interstitial/Slider/Floating

For more information, see Table 5.9 in the OpenRTB API Specification Version 2.5.

skip

Integer; optional

Specifies whether the player allows the video to be skipped, where:

• 0 is No
• 1 is Yes

playbackmethod

A list of allowed playback methods, where:

• 1 is Auto-play sound on
• 2 is Auto-play sound off
• 3 is Click-to-play
• 4 is Mouse-over

If blank, IX assumes that all methods are allowed.

pos

Integer; optional

Specifies the position of the ad as a relative measure of visibility or prominence, where:

• 0 is unknown
• 1 is above the fold (default)
• 2 is deprecated (resolution dependent)
• 3 is below the fold
• 4 is header
• 5 is footer
• 6 is sidebar
• 7 is full-screen

sequence

Integer; optional

If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.

startdelay

Integer; optional

Specifies the start delay in seconds for pre-roll, mid-roll, or post-roll ad placement, where:

• 0 is pre-roll
• -1 is generic mid-roll
• -2 is generic post-roll

w

Integer; optional

The width of the player, in pixels.

playertype

Integer; optional

Specifies the player type associated with this out-stream video impression, where:

• 1 is in news feed
• 2 is in article

If blank, the player is assumed to be a conventional in-steam type.

rewarded

Integer; optional

Specifies whether the ad is being rendered as a part of a rewarded video ad experience, where:

• 0 is False
• 1 is True

carrier

String; optional

The carrier or ISP. For example, “VERIZON”.“WIFI” is often used in mobile to indicate high bandwidth (for example, video friendly vs. cellular).

devicetype

Integer; optional

The device type in use for this impression, if available, where:

• 1 is mobile or tablet
• 2 is personal computer
• 3 is connected TV
• 4 is phone
• 5 is tablet
• 6 is connected device
• 7 is set-top box

didmd5

String; optional

didsha1

String; optional

dpidmd5

String; optional

dpidsha1

String; optional

geo

Object; optional

h

The physical height of the device screen, in pixels.

Note: Only supported in OpenRTB 2.3.

hwv

String; optional

Represents the hardware version of the device. For example, "5S" represents an iPhone 5S.

Note: Only supported in OpenRTB 2.3.

ifa

String; optional

ip

String; optional

A dotted-octet representation of the IPv4 address of the user.

Note: This field is required if the bid request does not contain the ipv6 field. See the ipv6 field below.

ipv6

String; optional

The IP address closest to the device, specified in IPv6 format (for example, "fe80:0:0:0:200:f8ff:fe21:67cf"). IX only sends bid requests for IPv6 traffic if you're able to support it. Contact your IX Representative if you want to start receiving IPv6 requests.

Note: IX always sends one of either device.ip or device.ipv6 in all bid requests.

language

String; optional

lmt

Integer; optional

Specifies the scope of tracking related to this impression. This signal represents a commercially adopted version (endorsed by iOS and Android) of standard do-not-track functionality, where:

• 0 specifies that tracking is unrestricted
• 1 specifies that tracking must be limited per commercial guidelines

Note: Only supported in OpenRTB 2.3.

macmd5

String; optional

macsha1

String; optional

make

String; optional

model

String; optional

os

String; optional

osv

String; optional

ppi

Integer; optional

The pixels per linear inch.

Note: Only supported in OpenRTB 2.3.

pxratio

Float; optional

The ratio of physical pixels to device-independent pixel.

Note: Only supported in OpenRTB 2.3.

ua

String; optional

The content of the HTTP_USER_AGENT header for this user. Anything above 512 characters is truncated.

w

Integer; optional

The physical width of the device screen, in pixels.

Note: Only supported in OpenRTB 2.3.

city

String; optional

The city, as per United Nations Code for Trade & Transport Locations. See UN/LOCODE Code List.

country

String; optional

The country code, using ISO-3166-1-alpha-3.

lat

Float; optional

The latitude from -90.0 to +90.0, where negative is south.

lon

Float; optional

The longitude from -180.0 to +180.0, where negative is west.

metro

String; optional

The Google metro code; similar to but not exactly Nielsen DMAs. See List of Google Metro Codes.

region

String; optional

regionfips104

String; optional

The region of a country using FIPS 10-4 notation. While OpenRTB supports this attribute, it has been withdrawn by NIST in 2008.

type

Integer; optional

The source of location data; recommended when passing lat and lon. See List of location types.

zip

String; optional

The zip code or postal code.

utcoffset

Integer; optional

The local time as the number +/- of minutes from UTC.

Note: Only supported in OpenRTB 2.3.

edepth

Integer; optional

The number of ad requests since a session was started with the user (max 255).

placement

Object; optional

The Placement Object.

sdepth

Integer; optional

The number of ad requests since a session was started with the user for the domain (max 255).

tz

Integer; optional

The user time zone derived from the JavaScript getTimezoneOffset() function.

name

String; optional

A name that describes why the impression is private (for example, "Homepage").

private

Boolean; optional

The scope of DSP bidding eligibility for this impression, where:

• 1 is private and eligible bids are restricted to the deals specified.

coppa

Integer; optional

Specifies whether this request is subject to the United States Children’s Online Privacy Protection Act (COPPA), where:

• 0 is no
• 1 is yes.

If this flag is omitted in the request, IX assumes that this information is unavailable.

Note: The following fields are automatically blanked in COPPA-related requests: lat, lon, metro, city and zip (in the Geo Object).

ext

Object; optional

The Regulation Extension Object, which is used to specify requests that are subject to regulations. See the table below.

gdpr

Integer; optional

Specifies whether the request is subject to regulations, where:

• 0 specifies that this request is not subject to regulations.
• 1 specifies that this request is subject to regulations

us_privacy

Object; optional

Specifies whether US privacy laws (for example, CCPA) apply or don't apply to the user in the bid request. This field contains four characters. For example, 1YYN. The meaning of each character is based on its position in the string as defined below:

• 1st character: The version number for the US privacy string specification used to encode the string.
• 2nd character: Specifies whether the user had explicit notice and the choice to opt-out of the sale of their personal information, where:.
  • N is No
  • Y is Yes
  • - is Not applicable
• 3rd character: Specifies whether the user has opted-out of the sale of their personal information.
  • N is No
  • Y is Yes
  • - is Not applicable
• 4th character: Specifies whether the publisher is a signed party to the IAB Limited Service Provider Agreement (LSPA). The publisher specifies whether the transaction is either a Covered Opt Out Transaction or a Non Opt Out Transaction.
  • N is No
  • Y is Yes
  • - is Not applicable

For example, a string passed as 1--- specifies that a US privacy regulation does not apply to the bid request.

Note: When a consumer chooses to opt-out of the sale of their personal information, the following bid request fields are automatically adjusted:

• ip (device object): The last octet of the user’s IP address is replaced with a zero.
• lat and lon (geo object): Latitude and longitude coordinates are reduced to two decimals which translates to accuracy no less than one third of a mile.
• All unique IDs from the bid request in the device and user objects that indirectly identify a user are removed.
• deals (pmp object): Audience segment targeted deal IDs are no longer added to the bid request.

id

String; required

The IX-assigned unique identifier for the website.

cat

Array of Strings; optional

A single-element array representing the standard IAB content category for the overall site. For example, ["IAB3-7"] See section 6.1 of the OpenRTB Specification (version 2.2) for a full list.

content

Object; optional

The Content Object.

domain

String; optional

A static value that represents the site’s domain.

mobile

Integer; optional

Specifies whether the site has been programmed to optimize layout when viewed on mobile devices, where:

• 0 is no
• 1 is yes

page

String; optional

The URL of the page where this impression will be shown.

publisher

Object; optional

The Publisher Object.

ref

String; optional

The referring URL that caused navigation to the page hosting this impression. Anything above 512 characters is truncated.

keywords

List; optional

A comma-separated list of brand safety flags for the site or app, represented as integers.

language

String; optional

The language of the content, specified using ISO-639-1-alpha-2.

id

String; required

The IX-specific publisher ID.

name

String; optional

A name that represents the publisher that can be masked if requested.

Note: This field is always present when a deal exists.

buyeruid

String; optional

A DSP's UID for this user (see user matching for format).

Note: This field is always present in default user match configuration.

id

String; optional

The IX static identifier for this user (contains only alphanumeric or the following characters: @ - . _ ).

Note: This field is always present in default user match configuration.

ext

Object; optional

The User Ext Object, which is used to indicate requests that contain certain user identifiers and are subject to GDPR regulations.

consent

String; optional

Specifies user consent when GDPR regulations are in effect. When present, it contains the data structure developed by the GDPR Consent Working Group. For more information, refer to the OpenRTB GDPR Advisory, published by the IAB.

eids

Array of objects; optional

An array of eIDs Objects, used to communicate email IDs for this user.

gdpr

Integer; optional

Specifies whether the request is subject to regulations, where:

• 1 specifies that this request is subject to regulations
• 0 specifies that this request is not subject to regulations.

If this field is omitted, IX assumes that the request's status is unknown. For more information, refer to the OpenRTB GDPR Advisory, published by the IAB.

source

String; optional

The source of the IDs. For example, "adserver.org".

uids

Array of objects; optional

An array of uIDs Objects.

id

String; optional

The user ID received in the request.

ext

Object; optional

The eIDs Extension Object.

rtipartner

String; optional

The name of the real-time Identity partner. For example, "tradedesk".

id

String; optional

The user ID. For example, "uid123".

ext

Object; optional

The uIDs Extension Object.

rtipartner

String; optional

The name of the real-time Identity partner. For example, "appnexus".