List of supported OpenRTB bid request fields
Our OpenRTB bidding API facilitates real-time bidding. Data for bid requests is sent in JSON RFC 4627 format and all fields are considered case-sensitive.
Bid request object
The top level bid request object and accompanying fields are below, followed by each lower level object contained within it.
Field | Type | Description |
---|---|---|
|
String; required |
The IX unique ID for the request (alphanumeric). |
|
Object; required |
The Impression Object; contains at least one Banner Object or Video Object. |
|
Object; required |
The Device Object. |
|
Object; required |
Maximum time in milliseconds that IX allows to receive bids. To avoid timeouts, the Note: If required, we can subtract latency when passing |
|
Required |
A custom IX Request Extension Object that contains additional information about the bid request. |
|
Object; optional |
The App Object; included if the impression originates from an application. |
|
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). |
|
Array of strings; optional |
A list of advertiser domains that have been blocked by the publisher from serving on their properties, for example |
|
Object; optional |
The Regulations Object. |
|
Object; optional |
The Site Object; included if the impression originates from a website. |
|
Object; optional |
The User Object. |
Source object
Payment ID Chain object
Field | Type | Description |
---|---|---|
|
String; optional |
The Payment ID chain string provides visibility into an impression's supply path. For bid requests sourced directly from IX, the For example, 50b1c356f2c5c8fc:2167. For bid requests sourced from a supplier, the 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. |
Source Ext object
Field | Type | Description |
---|---|---|
|
Object; optional |
Like To interpret the |
|
String; optional |
An identifier for the OM SDK integration. This is the same as the |
|
String; optional
|
A version of the OM SDK integration. This is the same as the |
Schain object
Field | Type | Description |
---|---|---|
|
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:
|
|
Object array; required |
An array of |
|
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. |
SupplyChainNode objects
Field | Type | Description |
---|---|---|
|
String; required
|
Domain name of the system that the bidder connects to. For example, SSP, exchange. Note: You can find the sellers. |
|
String; required |
The seller or reseller account ID. Note: Support for the |
|
String; optional |
The request's OpenRTB RequestId issued by the seller. Note: The same information can also be found in |
sid
|
String; required |
The seller or reseller account ID. Note: The same information can also be found in |
|
Integer; required |
Specifies whether this node is involved in the flow of payment for the inventory. The |
Imp object
This object describes an ad placement or impression opportunity being auctioned. A single impression opportunity may allow one or multiple creative types such as banner
and video
. Bid responses should only include creative types that are allowed for the respective impression opportunity.
banner
and video
creatives for a single impression opportunity. To enable multi-format requests, contact your IX Representative.Field | Type | Description |
---|---|---|
| String; required | A unique identifier for this impression. |
| 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 |
| Object; required | The Banner Object. Note: All requests must include at least one Banner Object or Video Object. |
| Integer; required | Specifies whether impressions require secure HTTPS URL creative assets and markup, where:
|
| Object; required | The Video object. Note: All requests must include at least one Video object or Banner object. |
| Float; optional | The minimum bid for this impression in CPM. |
| Object; optional | A custom IX Impression Extension Object that contains additional information about any deals for this impression. |
| Integer; optional | Specifies whether an ad is interstitial, where:
|
| Object; optional | The PMP Object that contains information about deals for this impression. |
PMP, Deals, and PMP Ext objects
PMP object
Field | Type | Description |
---|---|---|
| Integer; optional | The scope of DSP bidding eligibility for this impression, where:
|
| Array of Objects; optional | A collection of Direct Deals Objects containing any direct deals eligible for this impression. |
| Object; optional | A custom IX PMP Extension Object that contains additional information about this deal. |
Deals object
The PMP Object may contain one or more additional Deals Objects, each representing a different direct deal for this impression:
Field | Type | Description |
---|---|---|
| String; required | A unique identifier for this direct deal. |
| Integer; optional | The auction type for this direct deal, where:
|
| 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. |
| String; optional | A whitelist of buyer seats (for example, advertisers, agencies) that are allowed to bid on a deal. |
PMP Ext object
The PMP Object may contain an IX-custom PMP Ext Object, containing additional information about the direct deal.
Field | Type | Description |
---|---|---|
| String; optional | Placement name for all impressions operating in the private market. Example: "The Daily Times". |
Deals Ext object
To provide transparency to DSPs during an auction and to identify Post-Auction Discounts opportunities on deals, IX will pass the following disc
field in the deals.ext
object of a bid request:
Field | Type | Description |
---|---|---|
Float | A number between 0.01 - 1.0 representing the discount negotiated between a publisher and buyer. This value is applied to the Example: A 25% discount is sent as To learn more about discounts for deals, see Negotiating discounts on deals. |
Impression Ext object
This custom Extension Object communicates information regarding deals and Header Tag bids.
Field | Type | Description |
---|---|---|
| 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:
|
| 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 |
| Integer; optional | Specifies whether to use Header Tag inventory bid requests, where:
Note: This is not included by default and DSPs must request it. |
| String; optional | The White Ops MediaGuard |
App object
Field | Type | Description |
---|---|---|
| String; required | The IX-assigned unique numeric identifier for this app. |
| String; optional | The App name or bundle (for example, "com.foo.mygame"), used as a unique identifier across exchanges. |
| Array of Strings; optional | The standard IAB content category for the overall site (for example, [" |
| Object; optional | The Content Object. |
| Optional | A static value representing the domain of the app. |
| String; optional | A comma-separated list of keywords related to the app. |
| String; optional | The name of the app. It may be masked if requested by the publisher. |
| Integer; optional | Specifies whether the app is a paid or free version, where:
|
| Integer; optional | Specifies whether the app has a privacy policy, where:
|
| Object; optional | The Publisher Object. |
| String; optional | The App store URL for an installed app for QAG 1.5 compliance. |
| String; optional | The application version. |
Banner object
This object is a subset of the Impression object that describes a banner ad impression. If the auctioned impression is banner or rich media, include the Banner object directly in the Impression object. It can also be embedded in the Video object to describe companion banners available for linear/non-linear video ads. For information on the possible ad dimensions, see List of ad units and maximum expansion size.
Field | Type | Description |
---|---|---|
| Integer; required | The height of this impression, in pixels. |
| Boolean; required | Specifies whether the banner ad is delivered in the top frame or in an iFrame, where:
Note: Expandable ads must meet our expansion requirements. |
| Integer; required | The width of this impression, in pixels. |
| 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. |
| Integer; optional | The list of blocked creative types, where:
If left blank, IX assumes that all types are allowed. |
| Array of Integers; optional | Indicates expandable ad directions, where:
|
| Array of Integers; optional | Specifies the supported API frameworks, where:
By default, custom APIs are assumed as unsupported. |
| 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 |
| 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 |
| 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 |
| Array of Strings; optional | Whitelist of content MIME types supported. Popular MIME types include, but are not limited to |
| Integer; optional | Specifies the position of the ad as a relative measure of visibility or prominence where:
|
| 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 |
| 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 |
Video and Video Ext objects
Video object
Field | Type | Description |
---|---|---|
| Integer; required | Maximum video ad duration, in seconds. |
| Integer; required | Minimum video ad duration, in seconds. |
| Array of Strings; required | A list of supported video content MIME types. Popular MIME types supported by HTML5 players include:
For VPAID support, make sure to specify application/javascript. |
| Array of Integers; required | An array of supported video protocols. At least one supported protocol must be specified, where:
|
| Array of Integers; optional | A list of supported API frameworks, where:
By default, custom APIs are assumed to be unsupported. |
| Integer; optional | Specifies whether letter-boxing of 4:3 content into a 16:9 window is allowed, where:
|
| Array; optional | Specifies blocked creative attributes. If blank, it is assumed that all types are allowed. |
| Array of Objects; optional | Available companion ads are listed as an array of Banner Objects. |
| Array of Integers; optional | A list of supported VAST companion ad types, where:
|
| Array of Integers; optional | A list of supported delivery methods. If blank, it is assumed that all are supported, where:
|
| Object; optional | A custom IX Video Extension Object that contains additional information about this impression.
|
| Integer; optional | The height of the player, in pixels. |
| 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:
|
| Integer; optional | The maximum extended ad duration if extension is allowed, where:
|
| Integer; optional | The maximum bit rate in Kbps. |
| Integer; optional | The minimum bit rate in Kbps. |
| Integer; optional | The video's placement type, where:
For more information, see Table 5.9 in the OpenRTB API Specification Version 2.5. |
| Integer; optional
| Specifies whether the player allows the video to be skipped, where:
|
| Array of Integers; optional | A list of allowed playback methods, where:
If blank, IX assumes that all methods are allowed. |
| Integer; optional | Specifies the position of the ad as a relative measure of visibility or prominence, where:
|
| 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. |
| Integer; optional | Specifies the start delay in seconds for pre-roll, mid-roll, or post-roll ad placement, where:
|
| Integer; optional | The width of the player, in pixels. |
Video Ext object
This custom Extension Object indicates the player type associated with out-stream video impressions.
Field | Type | Description |
---|---|---|
| Integer; optional | Specifies the player type associated with this out-stream video impression, where:
If blank, the player is assumed to be a conventional in-steam type. |
| Integer; optional | Specifies whether the ad is being rendered as a part of a rewarded video ad experience, where:
|
Device object
Field | Type | Description |
---|---|---|
| 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). |
| Integer; optional | The device type in use for this impression, if available, where:
|
| String; optional | The hardware device ID , hashed via MD5. For example, IMEI . |
| String; optional | The hardware device ID, hashed via SHA1. For example, IMEI . |
| String; optional | The platform device ID, hashed via MD5. For example, Android ID . |
| String; optional | The platform device ID, hashed via SHA1. For example, Android ID . |
| Object; optional | The Geo object. |
| Integer; optional | The physical height of the device screen, in pixels. Note: Only supported in OpenRTB 2.3. |
| String; optional | Represents the hardware version of the device. For example, "5S" represents an iPhone 5S. Note: Only supported in OpenRTB 2.3. |
| String; optional | An ID sanctioned for advertiser use in the clear (not hashed). |
| 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 |
| 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 |
| String; optional | The first two characters of the header, in uppercase. For example, HTTP_ACCEPT_LANGUAGE "EN" |
| 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:
Note: Only supported in OpenRTB 2.3. |
| String; optional | MAC address of the device; hashed via MD5. |
| String; optional | MAC address of the device; hashed via SHA1. |
| String; optional | The device make. For example, "Apple". |
| String; optional | The device model. For example,"iPhone" |
| String; optional | The device operating system. For example, "iOS" |
| String; optional | The device operating system version. For example, “3.1.2" |
| Integer; optional | The pixels per linear inch. Note: Only supported in OpenRTB 2.3. |
| Float; optional | The ratio of physical pixels to device-independent pixel. Note: Only supported in OpenRTB 2.3. |
| String; optional | The content of the HTTP_USER_AGENT header for this user. Anything above 512 characters is truncated. |
| Integer; optional | The physical width of the device screen, in pixels. Note: Only supported in OpenRTB 2.3. |
Geo object
Field | Type | Description |
---|---|---|
| String; optional | The city, as per United Nations Code for Trade & Transport Locations. See UN/LOCODE Code List. |
| String; optional | The country code, using ISO-3166-1-alpha-3. |
| Float; optional | The latitude from -90.0 to +90.0, where negative is south. |
| Float; optional | The longitude from -180.0 to +180.0, where negative is west. |
| String; optional | The Google metro code; similar to but not exactly Nielsen DMAs. See List of Google Metro Codes. |
| String; optional | The region code using ISO-3166-2; 2-letter state code if USA ("US" ). |
| 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. |
| Integer; optional | The source of location data; recommended when passing lat and lon. See List of location types. |
| String; optional | The zip code or postal code. |
| Integer; optional | The local time as the number +/- of minutes from UTC. Note: Only supported in OpenRTB 2.3. |
Request Ext and Placement objects
Request Ext object
Field | Type | Description |
---|---|---|
| Integer; optional | The number of ad requests since a session was started with the user (max 255). |
| Object; optional | The Placement Object. |
| Integer; optional | The number of ad requests since a session was started with the user for the domain (max 255). |
| Integer; optional | The user time zone derived from the JavaScript getTimezoneOffset() function. |
Placement object
The Placement Object is always present for impressions in the private exchange.
Field | Type | Description |
---|---|---|
| String; optional | A name that describes why the impression is private (for example, "Homepage"). |
| Boolean; optional | The scope of DSP bidding eligibility for this impression, where:
|
Regulations and Regulations Ext objects
Regulations object
Field | Type | Description |
---|---|---|
| Integer; optional | Specifies whether this request is subject to the United States Children’s Online Privacy Protection Act (COPPA), where:
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). |
| Object; optional | The Regulation Extension Object, which is used to specify requests that are subject to regulations. See the table below. |
Regulations Ext object
Field | Type | Description |
---|---|---|
| Integer; optional | Specifies whether the request is subject to regulations, where:
|
| 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,
For example, a string passed as Note: When a consumer chooses to opt-out of the sale of their personal information, the following bid request fields are automatically adjusted:
|
Site object
Field | Type | Description |
---|---|---|
| String; required | The IX-assigned unique identifier for the website. |
| Array of Strings; optional | A single-element array representing the standard IAB content category for the overall site. For example, [" |
| Object; optional | The Content Object. |
| String; optional | A static value that represents the site’s domain. |
| Integer; optional | Specifies whether the site has been programmed to optimize layout when viewed on mobile devices, where:
|
| String; optional | The URL of the page where this impression will be shown. |
| Object; optional | The Publisher Object. |
| String; optional | The referring URL that caused navigation to the page hosting this impression. Anything above 512 characters is truncated. |
Content and Publisher objects
Content object
Field | Type | Description |
---|---|---|
| List; optional | A comma-separated list of brand safety flags for the site or app, represented as integers. |
| String; optional | The language of the content, specified using ISO-639-1-alpha-2. |
Publisher object
Field | Type | Description |
---|---|---|
| String; required
| The IX-specific publisher ID. |
| String; optional | A name that represents the publisher that can be masked if requested. Note: This field is always present when a deal exists. |
User and User Ext objects
User object
Field | Type | Description |
---|---|---|
| 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. |
| 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. |
| Object; optional | The |
User Ext object
Field | Type | Description |
---|---|---|
| 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. |
| Array of objects; optional | An array of eIDs Objects, used to communicate email IDs for this user. |
| Integer; optional | Specifies whether the request is subject to regulations, where:
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. |
eIDs object
Field | Type | Description |
---|---|---|
| String; optional | The source of the IDs. For example, "adserver.org". |
| Array of objects; optional | An array of uIDs Objects. |
| String; optional | The user ID received in the request. |
| Object; optional | The eIDs Extension Object. |
eIDs Ext object
Field | Type | Description |
---|---|---|
| String; optional | The name of the real-time Identity partner. For example, " |
uIDs object
Field | Type | Description |
---|---|---|
| String; optional | The user ID. For example, " |
| Object; optional | The uIDs Extension Object. |
uIDs Ext object
Field | Type | Description |
---|---|---|
| String; optional | The name of the real-time Identity partner. For example, " |