List of supported OpenRTB bid request fields for sellers

Integrated partners send bid requests to Index Exchange (Index) with the parameters of biddable impression opportunities. Index sends requests of its own to integrated demand partners to retrieve bids. This topic lists Index's supported bid request fields for OpenRTB S2S integrations. To learn more about these fields, refer to the Interactive Advertising Bureau (IAB) OpenRTB 2.5 specification. For OpenRTB bid request examples, see Examples of OpenRTB bid requests and responses.

OpenRTB protocol differences

The Index bidding API differs slightly from the guidelines outlined in the IAB OpenRTB Specification. The following table lists these differences:

Field IAB scope Index scope

ip (in the Device Object)

Recommended

Index requires the ip field only if the IPV6 field is not provided in the bid request device object.

domain and page (in the Site Object)

Recommended

Index requires all bid requests to include either the domain or page field in the site object. Bid requests that are missing both of the fields are considered invalid.

Deal configuration

You can create Private Marketplace Deals (PMP) deals with various demand partners. After the deals are created and made active, the deal parameters are either communicated within the bid request or inferred from the bid request. For more information about deal configuration options, see Deal configuration options in an OpenRTB integration.

Supported OpenRTB bid request fields

The following table lists the Index required and optional fields in the OpenRTB S2S integration. If your integration does not include the required fields, contact us before beginning the integration process.

Note:

  • All fields are considered case-sensitive.
  • Make sure to send data for bid requests in JSON RFC4627 format, following the OpenRTB standard.

BidRequest object

Index supports the following fields in the top-level bid request object.

Field Type Description

id

String; required

The unique alphanumeric ID for the request.

imp

Object array; required

An array with a single Impression Object, containing a single Banner Object or Video Object.

device

Object; required

The Device Object that contains information about the user’s device to which the impression will be delivered.

app

Object; optional

The App Object is included if the impression originates from an application. It contains details about the publisher’s app (for example., a non-browser application).

tmax

Object; required

The maximum time, in milliseconds, to submit a bid to avoid timeout. The minimum tmax value that Index allows on a bid request is 100ms.

Note: If required, we subtract latency when passing the tmax value to DSPs. For more information, contact your Index Representative.

at

Integer; optional

The auction type for the bid request. This value should always be 1 = first price auction.

Note: The second price auction type is deprecated and no longer supported.

cur

String array; optional

The currencies that publishers will accept in bid responses. Currencies must be specified in the ISO-4217 standard and must be supported by Index. For more information, see List of supported currencies.

badv

String array; optional

An array of strings that specify any blocked top-level domains of advertisers. For example, ["companyA.com", "companyB.com"].

bcat

String array; 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 2.5 Specification.

ext

Object; optional

A custom Index Request Extension Object containing additional information about this bid request.

regs

Object; optional

The Regulations Object that specifies any industry, legal, or governmental regulations in force for this request.

site

Object; optional

The Site Object containing details about the publisher’s website. It is included only if the impression originates from a website.

test

Integer; optional

Specifies whether the auction is operating in test mode, in which case auctions for this impression are not billable, where:
  • 0 = live mode (default)
  • 1 = test mode

user

Object; optional

The User Object containing details about the user of the device; the advertising audience.

source Object; optional A Source object that provides data about the inventory source.

BidRequest extension object

Field Type Description

ssl

Integer; optional

Specifies whether the impression requires secure HTTPS URL creative assets and markup, where:
  • 0 = secure assets are not required
  • 1 = impression requires secure assets and markup

If this field is not present, Index interprets that the secure state is unknown and assumes HTTP is supported.

Source object

Field Type Description

pchain

String; optional

The Payment ID chain string provides visibility into an impression's supply path. For bid requests sourced directly from Index, the pchain field will display:

  • Index's TAG ID of 50b1c356f2c5c8fc

  • Publisher ID, such as 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 Index. 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.

ext

String; optional

The Source Ext object which is used to specify additional details about the source of the bid request. For more information, see the Source extension object below.

Source extension object

Field Type Description

schain

Object; optional

The supply chain object. 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.

Note: Index only supports receiving schain in bidrequest.source.ext.schain. Make sure that you are always passing schain to Index in bidrequest.source.ext.schain.

For more information, see the Supply chain object below.

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.

SupplyChain object

Field Type Description

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 = no
  • 1 = yes

nodes

Object array; required

An array of Node 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. For more information, see Supply Chain Node objects below.

ver

String; required

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

Nodes object

Field Type Description

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 of the corresponding advertising system participating in the transaction for each node through this domain name.

rid

String; optional

The request's OpenRTB RequestId issued by the seller.

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

sid

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. Index's node will always include hp=1. For version 1.0 of SupplyChain, this field should always be 1.

Regs object

Field Type Description

coppa

Integer; optional

Specifies whether this request is subject to the United States Children’s Online Privacy Protection Act (COPPA), where:
  • 0 = request is not subject to regulations
  • 1 = request is subject to regulations
If this flag is omitted in the request, Index assumes that this information is unavailable.

ext

Object; optional

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

Regs extension object

Field Type Description

gdpr

Integer; optional

Specifies whether the request is subject to regulations, where:

  • 0= request is not subject to regulations
  • 1 = request is subject to regulations

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

Imp object

This object describes an ad placement or impression opportunity being auctioned. A single impression opportunity can include one or multiple creative types such as banner and video.

Field Type Description

id

String; required

A unique identifier for this impression.

banner

Object; required

The Banner Object.

Note: Requests including both a Banner Object and a Video Object are currently not supported.

video

Object; required

The Video Object.

Note: Requests including both a Banner Object and a Video Object are currently not supported.

native Object; required The Native object. This field is required if this impression is offered as a native ad opportunity.

Note: The Native object is currently in Beta testing. For more information on how Index supports native ads, contact your Index Representative.

bidfloor

Float; optional

The minimum bid for this impression in CPM.

bidfloorcur

String; optional

The currency for the bid floor. Currencies must be specified in the ISO-4217 standard and must be supported by Index. For more information, see List of supported currencies.

instl

Integer; optional

Specifies whether an ad is interstitial, where:

  • 0 = ad is not interstitial
  • 1 = ad is interstitial or full screen

ext

Object; optional

A custom Index Impression extension object containing additional information about this impression.

pmp

Object; optional

The PMP Object containing information about deals for this impression.

metric

Object; optional

The Metric object that contains more information about any metrics associated with this impression.

rwdd

Integer; optional

Indicates if this impression is associated with a rewarded placement, where:

  • 0 = ad is not a rewarded placement
  • 1 = ad is a rewarded placement

secure

Object; optional

A flag to specify whether the impression requires secure HTTPS URL creative assets and markup, where:

  • 0 = HTTPS URL is not required
  • 1 = HTTPS URL is required

If this field is not present, the secure state is interpreted as being unknown and it is assumed that HTTP is supported.

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 specifying where the ad is located on a web page to optimize and troubleshoot buyer campaigns.

Note: tagid only applies to server-to-server and GoogleOpen Bidding integrations. If you specify the tagid, Index will pass the same tagid to DSPs. If you do not specify the tagid, Index will pass its own site ID instead.

Imp extension object

The imp object may include an extension object. It provides additional information about the impression opportunity.

Field Type Description

skadn

Object; optional

Specifies publisher support for Apple's SKAdNetwork app install attribution. See SKAdNetwork extension object below.

dfp_ad_unit_code

String; optional

The Google Ad Manager ad unit code of the ad slot that the bid request was sent for. This will be used as a fallback for the Global Placement Identifier (GPID) if the below gpid field is not available. For more information about GPID, see Send the Global Placement Identifier (GPID) to Index.

gpid

String; optional

The Global Placement Identifier (GPID) for the ad slot or placement. This should be a unique ad unit code that corresponds to the request coming from the ad slot or placement. For more information about GPID, see Send the Global Placement Identifier (GPID) to Index.
Note:

  • If this field is not present, Index will fallback to using the dfp_ad_unit_code as the GPID.

  • The gpid field has the same purpose as the tagid field, however some demand sources require that you pass the gpid field instead of the tagid field.

tid

String; optional

The unique transaction ID for each impression, which is common across all the exchanges that are bidding on this impression opportunity. This field is an implementation of OpenRTB's community extension for Per-Impression Transaction IDs.

SKAdNetwork extension object

The skadn object may include an extension object. To learn more, see OpenRTB SKAdNetwork extension.

Field Type Description

version

String; optional

The version of skadnetwork supported. This field is always "2.0" or higher and is dependent on both the OS version and the SDK version.

Note: With the release of SKAdNetwork 2.1, this field is deprecated in favor of the versions field to support an array of version numbers.

versions

String array; optional

An array of strings containing the supported skadnetwork versions. This field is always "2.0" or higher and is dependent on both the OS version and the SDK version.
Example: "versions": ["2.0", "2.1", "2.2"]

sourceapp

String; optional

The ID of the publisher app in Apple’s app store. It should match the app.bundle in OpenRTB 2.x and app.storeid in AdCOM 1.x.
Example: "sourceapp": "880047117"

skadnetids

String array; optional

A subset of SKAdNetworkItem entries in the publisher app’s Info.plist, expressed as lowercase strings, that are relevant to the bid request. It is recommended that this list does not exceed 10.
Note: BidRequest.imp.ext.skadn.skadnetlist.addl is the preferred method to express raw SKAdNetwork IDs.
skadnetlist Object; optional An object containing the IAB's list definition. See skadnetlist object below.
Example: "skadnetlist": {"max": 306, "excl": [2,8,10,123], "addl": ["cdkw7geqsh.skadnetwork", "qyJfv329m4.skadnetwork"]}

Skadnetlist object

This object provides the IAB's skadnetwork object list fields.

Field Type Description

max

Integer; optional

A list containing the max entry ID of SKAdNetwork ID.
Example: "max":306.

excl

Integer array; optional

A comma separated list of IAB registration IDs that are to be excluded from the IAB shared list.
Example: "excl": [44,14,18]

addl

String array; optional

A comma separated list of string SKAdNetwork IDs, expressed as lowercase strings, not included in the IAB shared list. It is recommended that this list should not exceed 10 IDs.
Example: "addl": ["cdkw7geqsh.skadnetwork", "qyjfv329m4.skadnetwork"]

Metric object

The metric object is associated with an impression as an array of metrics. These metrics can offer insight into the impression, such as recent viewability, completion rate, and click-through rate. Each metric is identified by its type, the value of the metric, and optionally the source or vendor that measured the value.

Field Type Description
type

String; required

The type of metric being presented. Index supports the following metric types: 

  • click_through_rate

  • session_depth

  • video_completion_rate

  • viewability

value

Float; required

A number representing the value of the metric. Probabilities must be in the range of 0.0 - 1.0.

vendor

String; optional

The source of the value using exchange curated string names. Index passes through this value from the media owner if provided. For any value produced by Index, the vendor is "INDEXEXCHANGE".

Banner object

This object is a subset of the Impression Object that describes a banner ad impression. If the impression offered for auction is for banner or rich media, make sure to include the banner object directly into the Impression Object. You can optionally embed it in the Video Object to describe the companion banners available for the linear or non-linear video ad. For information on the supported ad dimensions for a banner impression, see List of supported ad sizes

Note: You can send multi-size requests that include multiple ad sizes for an impression opportunity in a single request. For example, you can send a single bid request for a banner ad impression that supports 728x90, 970x90, and 970x250 sizes.

Field Type Description

format

Objects array; optional

Array of format objects specifying the banner sizes permitted for an impression opportunity.

h

Integer; required

The height of this impression, in pixels. See List of supported ad sizes

w

Integer; required

The width of this impression, in pixels. See List of supported ad sizes

api

Integer array; optional

Specifies the supported API frameworks, where:
  • 1 = VPAID 1.0
  • 2 = VPAID 2.0
  • 3 = MRAID 1.0
  • 4 = ORMMA
  • 5 = MRAID 2.0
  • 6 = MRAID 3.0
  • 7 = OMID 1.0

By default, custom APIs are assumed as unsupported.

battr

Integer array; optional

Specifies blocked creative attributes; it is preferred that only one attribute is passed. In addition to the standard creative attributes, Index supports the following mapping:
500 Overlay

btype

Integer array; optional

A list of blocked creative types, where:
  • 1 = XHTML text ad
  • 2 = XHTML banner ad
  • 3 = JavaScript ad
  • 4 = iframe

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

expdir

Integer array; optional

Specifies expandable ad direction, where:
  • 1 = left
  • 2 = right
  • 3 = up
  • 4 = down
  • 5 = fullscreen

hmax

Integer; 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

Integer; 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 impression.

mimes

string array; optional

 

Allowed list of content MIME types supported. Popular MIME types include but are not limited to: image/jpgand image/gif.

pos

Integer; optional

Specifies the position of the ad as a relative measure of visibility or prominence where:
  • 0 = unknown
  • 1 = above the fold (default)
  • 2 = deprecated (resolution dependent)
  • 3 = below the fold
  • 4 = header
  • 5 = footer
  • 6 = sidebar
  • 7 = full-screen

topframe

Integer; optional

Specifies whether the banner is in the top frame, as opposed to an iframe, where:
  • 0 = no
  • 1 = yes

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.

Video object

If the impression offered for auction is video, make sure to include the video object directly into the Impression object.

Field Type Description

h

Integer; required

The height of the player, in pixels.

maxduration

Integer; required

The maximum video ad duration in seconds.

minduration

Integer; required

The minimum video ad duration in seconds.

mimes

String array; required

List of supported content MIME types. Popular MIME types supported by HTML5 players include: video/mp4, video/webm, and video/ogg. For VPAID support, make sure to specify application/javascript.

Note: If you include application/javascript for VPAID, make sure to also specify the supported api framework (1 is VPAID 1.0 and 2 is VPAID 2.0).

protocols

Integer array; required

An array of supported video protocols. At least one supported protocol must be specified, where:
  • 2 = VAST 2.0
  • 3 = VAST 3.0
  • 5 = VAST 2.0 Wrapper
  • 6 = Vast 3.0 Wrapper

w

Integer; required

The width of the player, in pixels.

api

Integer array; optional

A list of supported API frameworks, where:
  • 1 = VPAID 1.0
  • 2 = VPAID 2.0
  • 3 = MRAID 1.0
  • 4 = ORMMA
  • 5 = MRAID 2.0
  • 6 = MRAID 3.0
  • 7 = OMID 1.0

By default, custom APIs are assumed to be unsupported.

Note: Only specify support for VPAID API if you want to receive VPAID ads.

boxingallowed

Integer; optional

Specifies whether letter-boxing of 4:3 content into a 16:9 window is allowed, where:
  • 0 = boxing is not allowed
  • 1 = boxing is allowed (default setting)

battr

Integer array; optional

 

Specifies blocked creative attributes; it is preferred that only one attribute is passed. In addition to the standard creative attributes, Index supports the following mapping:
500 Overlay

companionad

Object array; optional

If companion ads are available, they can be listed as an array of Banner Objects.

companiontype

Integer array; optional

A list of supported VAST companion ad types, where:
  • 1 = static Resource
  • 2 = HTML Resource
  • 3 = iframe Resource

delivery

Integer array; optional

A list of supported delivery methods. If blank, it is assumed that all are supported, where:
  • 1 = streaming
  • 2 = progressive

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 = linear/in stream
  • 2 = non-linear/overlay

skip

Integer; optional

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

  • 0 = no
  • 1 = yes

skipmin

Integer; optional

Videos of total duration greater than this number of seconds

can be skippable; only applicable if the ad is skippable.

skipafter

Integer; optional

Number of seconds a video must play before skipping is

enabled; only applicable if the ad is skippable.

maxextended

Integer; optional

The maximum extended ad duration if extension is allowed, where:
  • Blank or 0 = extension is not allowed.
  • -1 = extension is allowed and there is no time limit imposed.
  • Greater than 0 = 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 = in stream
  • 2 = in-banner
  • 3 = in-article
  • 4 = in-feed
  • 5 = interstitial/slider/floating

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

playbackmethod

Integer array; optional

A list of allowed playback methods, where:
  • 1 = auto-play sound on
  • 2 = auto-play sound off
  • 3 = click-to-play
  • 4 = mouse-over

If blank, Index 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 = unknown
  • 1 = above the fold (default)
  • 2 = deprecated (resolution dependent)
  • 3 = below the fold
  • 4 = header
  • 5 = footer
  • 6 = sidebar
  • 7 = 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 = mid-roll (value indicates start delay in second)
  • 0 = pre-roll
  • -1 = generic mid-roll
  • -2 = generic post-roll

Video extension object

The video object may include an Extension object. It provides additional information about the video impression opportunity.

Field Type Description

rewarded

Integer; optional

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

  • 0 = false
  • 1 = true

Native object

The presence of a native object as a subordinate of the impression object indicates that this impression is offered as a native type impression. At the publisher’s discretion, that same impression may also be offered as banner, video, or audio by also including them as imp subordinate objects of those types.

Field Type Description

request

String; required

The request payload complying with the OpenRTB Dynamic Native Ads API Specification Version 1.2. For more information about the native.request object, see List of supported OpenRTB bid request fields for native ads for Sellers (Beta).

ver

String; optional

The version of the native markup in use.

api

Integer array; optional

The list of supported API frameworks for the impression. If an API is not listed, assume it is not supported.

battr

Integer array; optional

The blocked creative attributes. To learn more, see the List of creative attributes.

Format object

The format object specifies an allowed size, in height and width combination, for a banner impression opportunity. These are typically used in an array where multiple sizes are permitted.

Field type Description

h

Integer; optional

The height in device-independent pixels.

w

Integer; optional

The width in device-independent pixels.

PMP and Deal objects

PMP object

Include any private marketplace active deals for the impression in the PMP object.

Field Type Description

private_auction

Integer; optional

The scope of bidding eligibility for this impression, where:
  • 0 = public and all bids are eligible
  • 1 = private and eligible bids are restricted to the deals specified

If omitted, bidding eligibility is determined based on the seller's deal configuration in the Index system.

deals

Object array; optional

A collection of Deal Objects, containing any direct deals eligible for this impression.

 

Deal object

Field Type Description

id

String; required

A unique identifier for the direct deal.

at

Integer; optional

An optional override of the overall auction type of the bid request, where:
  • 1 = first price
  • 3 = the value passed in bidfloor is the agreed upon deal price

Note: The second price auction type is deprecated and no longer supported.

Additional auction types can be defined by the exchange.

bidfloor

Float; optional

The designated floor price for this direct deal, in USD.

Note: This value must be sent in dollars.

bidfloorcur

String; optional

The currency for the bid floor. Currencies must be specified in the ISO-4217 standard and must be supported by Index. For more information, see List of supported currencies.

wseat

String array; optional

An array of buyer seats eligible to bid on this direct deal. For example:

["6", "22", "35", "17"]

wadomain

String array; optional

An array of advertiser domains eligible to bid on this direct deal. For example:

["advertiser1.com","advertiser2.com"]

Site object

Field Type Description

cat

String array; optional

A single-element array representing the standard IAB content category for the overall site. For example, ["IAB3-7"] The full list is available in section 5.1 of the OpenRTB 2.5 Specification.

content

Object; optional

Details about the content within the site. For more information about the content object, see the content object below.

domain

String; optional

A static value representing the domain of the site. Anything above 512 characters is truncated.

Note: This is a required field if the page attribute is omitted.

id

String; optional

A unique identifier for the website, defined by the seller.

keywords

String; optional

A comma separated list of keywords that describe the site. Maximum of 255 characters, additional characters will be truncated.

Note: Do not include personal data, personal information, or sensitive information.

mobile

Integer; optional

Specifies whether the site has been programmed to optimize layout when viewed on mobile devices, where:
  • 0 = no
  • 1 = yes

page

String; optional

The URL of the page where this impression will be shown. Anything above 512 characters is truncated.

Note: This is a required field if the domain attribute is omitted.

pagecat

Array of strings; optional

Content categories that describe the current page or view of the site. These categories are defined by the IAB and outlined in List 5.1 in Version 2.5 of the OpenRTB specification.

producer

Object; optional

Provides details about the producer of the content. For more information about the producer object, see the producer object below.

ref

String; optional

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

search

String; optional

A search string that resulted in the user navigating to the current page. Maximum of 255 characters, additional characters will be truncated.

Note: This field will be available to publishers in setting up deals, but the field will not be sent in bid requests to DSPs.

sectioncat

Array of strings; optional

Content categories that describe the current section of the site. These categories are defined by the IAB and outlined in List 5.1 in Version 2.5 of the OpenRTB specification.

App object

Field Type Description

bundle

string; optional

Application bundle or package name (for example, "com.foo.mygame") that is intended to be a unique ID across exchanges.

content

object; optional

Details about the content within the app. For more information about the content object, see the content object below.

domain

string; optional

A static value representing the domain of the app.

id

string; optional

Unique, numeric identifier for this app, defined by the seller.

keywords

string; optional

A comma separated list of keywords about the app. Maximum of 255 characters, additional characters will be truncated.

Note: Do not include personal data, personal information, or sensitive information.

name

string; optional

The app name which may be aliased at the publisher’s request.

pagecat

array of strings; optional

Content categories that describe the current page or view of the app. These categories are defined by the IAB and outlined in List 5.1 in Version 2.5 of the OpenRTB specification.

paid

integer; optional

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

  • 0 = the app is free
  • 1 = the app is a paid version

privacypolicy

integer; optional

Specifies whether the app has a privacy policy, where:

  • 0 = no
  • 1 = yes

producer

object; optional

The Producer object. Provides details about the producer of the content. For more information about the producer object, see the producer object below.

sectioncat

array of strings; optional

Content categories that describe the current section of the app. These categories are defined by the IAB and outlined in List 5.1 in Version 2.5 of the OpenRTB specification.

storeurl

string; optional

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

ver

string; optional

The application version.

ext

object; optional

The App extension object, which is used to provide more information about the app impression opportunity.

App extension object

The app object may include an Extension object. It provides additional information about the app impression opportunity.

Field Type Description

inventorypartnerdomain

String; optional

A pointer to the domain of a partner that is explicitly authorized to monetize ads within this application's content. The partner's corresponding appads.txt or ads.txt file will be hosted at this domain and can be used for supply chain validation.

For more information about how to implement this field, see the IAB's ads.txt Specification.

 

Content and Producer objects

Content object

Field Type Description

album

String; optional

The album to which the content belongs, typically for audio.

artist

String; optional

The artist who is credited with the content.

cat

String array; optional

A single-element array representing the standard IAB content category for the overall site. For example, ["IAB3-7"]. The full list is available in section 5.1 of the OpenRTB 2.5 Specification.

channel

Object; optional

The Channel object.

contentrating

String; optional

The content's rating (for example, MPAA).

context

Integer; optional

Refers to the type of content, where:

  • 1 = video (video file or internet TV broadcast)

  • 2 = game (interactive software game)

  • 3 = music (audio file or internet radio broadcast)

  • 4 = application (interactive software application)

  • 5 = text (web page, eBook, news article)

  • 6 = other

  • 7 = unknown

data

Object array; optional

Provides additional content data. See the Data object table.

embeddable

Integer; optional

Indicator of whether or not the content is embeddable, where:

  • 0 = no

  • 1 = yes

episode

String; optional

Episode number that applies to video content.

ext

Object; optional

A placeholder for Index-specific extensions to the content object. See the Content extension object table below.

genre

String; optional

The genre that best describes the content. For example, rock, pop, etc.

id

String; optional

ID that uniquely identifies the content.

isrc

String; optional

International Standard Recording Code, conforming to ISO-3901.

keywords

String; optional

A comma separated list of keywords describing the content.

language

String; optional

The first two characters of the language, in uppercase, as per ISO-639-1-alpha-2. For example, "EN".

len

Integer; optional

Specifies the length of the content in seconds used for video and audio.

livestream

Integer; optional

Specifies if the content is live (for example, a stream or live blog), where:

  • 0 = not live

  • 1 = content is live

network

Object; optional

The Network object.

prodq

Integer; optional

Refers to the production quality, where:

  • 0 = unknown

  • 1 = professionally produced

  • 2 = prosumer

  • 3 = user generated content (UGC)

producer

Object; optional

Details about the content producer. For more information, see producer object below.

qagmediarating

Integer; optional

The media rating as per Quality Assurance Guidelines (QAG), where:

  • 1 = all audiences

  • 2 = everyone over 12

  • 3 = mature audiences

season

String; optional

The season of the content (for example, "Season 3").

series

String; optional

Content series.

sourcerelationship

Integer; optional

Specifies the relationship to the source, where:

  • 0 = indirect

  • 1 = direct

title

String; optional

The title of the content.

url

String; optional

URL of the content for buy-side contextualization or review.

userrating

String; optional

How users have rated the content. For example, number of stars, number of likes.

videoquality

Integer; optional

Refers to the video quality.

Content extension object

The content object may include an Index-specific extension object that describes the impression content.

Field Type Description

channel

String; optional

The specific channel that the content is playing on.

Note: This field and the content_channel field are interchangeable. You can include either one.

content_channel

String; optional

The specific channel that the content is playing on.

Note: This field and the channel field are interchangeable. You can include either one.

network

String; optional

The parent content network that contains several channels.

Note: This field and the content_network field are interchangeable. You can include either one.

content_network

String; optional

The parent content network that contains several channels.

Note: This field and the network field are interchangeable. You can include either one.

distrib_name

String; optional

The alternate name under which the publisher distributes the content.

Producer object

Field Type Description

cat

String array; optional

A single-element array representing the standard IAB content category for the overall site. For example, ["IAB3-7"]. The full list is available in section 5.1 of the OpenRTB 2.5 Specification.

domain

String; optional

The highest level domain of the content producer. For example, "producer.com".

ext

Object; optional

A placeholder for Index-specific extensions to the producer object.

id

String; optional

An ID that represents the content producer or originator. This attribute is useful if the content is syndicated and posted on a site using embed tags.

name

String; optional

The name of the content producer or originator. For example, "Warner Bros".

Channel object

This object describes the channel an ad will be displayed on. A channel is defined as the entity that curates a content library or stream within a brand name for viewers, such as MTV.

Field Type Description

id

String; optional

A unique identifier assigned by the publisher. This is a unique identifier across all supply sources.

name

String; optional

The channel that the content is on, for example "MTV".

domain

String; optional

The primary domain of the channel, for example "mtv.com"

It's recommended to include the top level domain so it's easier for DSPs to target.

Network object

This object describes the network an ad will be displayed on. A network is defined as the parent entity of the Channel object’s entity, and is used for the purposes of organizing channels. An example of a network is a company that owns or licenses a collection of content channels, such as Discovery.

Field Type Description

id

String; optional

A unique identifier assigned by the publisher. This is a unique identifier across all supply sources.

name

String; optional

The network the content is on, for example "Discovery"

domain

String; optional

The primary domain of the network, for example "discovery.com"

It's recommended to include the top level domain so it's easier for DSPs to target.

Device object

Field Type Description

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

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

carrier

String; optional

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

devicetype

Integer; optional

The device type in use for this impression, if available, where:
  • 1 = mobile or tablet
  • 2 = personal computer
  • 3 = connected TV
  • 4 = phone
  • 5 = tablet
  • 6 = connected device
  • 7 = set-top box

didmd5

String; optional

The hardware device ID , hashed via MD5. For example, IMEI

didsha1

String; optional

The hardware device ID, hashed via SHA1. For example, IMEI

dpidmd5

String; optional

The platform device ID, hashed via MD5. For example, Android ID

dpidsha1

String; optional

The platform device ID, hashed via SHA1. For example, Android ID

geo

Object; optional

The Geo Object.

h

Integer; optional

The physical height of the device screen, in pixels.

hwv

String; optional

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

connectiontype

Integer; optional

The network connection type that the device uses, where:

  • 0 = unknown

  • 1 = ethernet

  • 2 = WiFi

  • 3 = cellular network - unknown generation

  • 4 = cellular network - 2G

  • 5 = cellular network - 3G

  • 6 = cellular network - 4G

ifa

String; optional

An ID sanctioned for advertiser use in the clear (not hashed). It is an identifier for ads with privacy support and is used along with the device.lmt and device.ext.ifa_type fields.

language

String; optional

The first two characters of the header, in uppercase. For example, HTTP_ACCEPT_LANGUAGE "EN"

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 = tracking is unrestricted
  • 1 = tracking must be limited per commercial guidelines

macmd5

String; optional

The MAC address of the device; hashed via MD5.

macsha1

String; optional

The MAC address of the device; hashed via SHA1.

make

String; optional

The device make. For example, "Apple"

model

String; optional

The device model. For example,"iPhone"

os

String; optional

The device operating system. For example, "iOS"

osv

String; optional

The device operating system version. For example, “3.1.2"

ppi

Integer; optional

The pixels per linear inch.

pxratio

Float; optional

The ratio of physical pixels to device-independent pixel.

ua

String; optional

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

If both the ua and sua fields contain values, sua is considered more accurate because the ua value may contain a frozen or reduced user agent string.

sua Object; optional The structured user agent information specified in the UserAgent object. If both the ua and sua fields contain values, sua is considered more accurate because the ua value may contain a frozen or reduced user agent string.

w

Integer; optional

The physical width of the device screen, in pixels.

ext

Integer; optional

A placeholder for Index specific extensions to the device object. See Device extension object below.

Device extension object

The device object may include an extension object to indicate the app's app tracking authorization status and IDFV. It may also include the Identifier for Advertising (IFA) source value according to the IAB Tech Lab's Guidelines for Identifier for Advertising (IFA) on CTV/OTT platforms.

Field Type Description

ifv

String; optional

The IDFV of the device with the publisher.

atts

Integer; optional

An iOS only field that is passed to represent the app's app tracking authorization status, where:

  • 0 = not determined

  • 1 = restricted

  • 2 = denied

  • 3 = authorized

ifa_type

String; optional

A value indicating the source of the IFA value, whether it is device-generated, provided by the publisher, or is a temporary session IFA. The supported values are:

  • dpid = The generic device provided ID.

  • rida = The Roku ID.

  • aaid = The Android ID.

  • idfa = The Apple ID.

  • afai = The Amazon Fire ID.

  • msai = The Microsoft ID.

  • tifa = The Samsung Tizen ID.

  • vida = The Vizio ID.

  • ppid = The publisher provided ID.

  • sspid = The SSP provided ID.

  • sessionid = A temporary IFA ID. For example, publishers or SSPs might generate a temporary IFA in the absence of an IFA from the publisher or device, so that tasks like frequency capping can be supported. This value is also used in place of the device's IFA if the user has opted out of ad tracking (device.lmt=1).

For more information about ifa_type, see IAB Tech Lab's Guidelines for Identifier for Advertising (IFA) on CTV/OTT platforms.

Geo object

Field Type Description

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

The region code using ISO-3166-2; 2-letter state code if USA ("US").

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.

User object

Field Type Description

buyeruid

String; optional

The Index UID for the user (case-sensitive). This value may be sent in either format:
  • URL encoded format: The allowed values are A-Z, a-z, 0-9, - (hyphen), . (period), & (ampersand), @ (at sign), % (percent sign). For example: Vjc1MMAoJ2YAADrj5sUAAABe%26136
  • URL decoded format:The allowed values are A-Z, a-z, 0-9, - (hyphen), . (period), & (ampersand), @ (at sign). For example:

    Vjc1MMAoJ2YAADrj5sUAAABe&136

Sellers may send a blank string or 0 in this field to indicate a "no match" user.

Note: This field is required for matched users.

data

Array of objects; optional

This object allows publishers to pass additional attributes about the user or content. See the Data object.

ext

Object; optional

The User extension object. See user extension object.

gender

String; optional

The gender of the user, where:

  • F = female

  • M = male

  • O = known to be other

If the gender of the user is unknown, this field is omitted.

Note: This field will be available to publishers in setting up deals, but the field will not be sent in bid requests to DSPs.

geo

Object; optional

The Geo object.

keywords

String; optional

A comma separated list of interests, intent, or keywords about the user. Maximum of 255 characters, additional characters will be truncated.

Note: This field will be available to publishers in setting up deals, but the field will not be sent in bid requests to DSPs.

yob

Integer; optional

The user's year of birth, as a four digit integer.

Note: This field will be available to publishers in setting up deals, but the field will not be sent in bid requests to DSPs.

User extension object

Field Type Description

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 containing extended third-party identifiers for this user. For more information, see eIDs object below.

UserAgent object

Field Type Description

browsers

Array of objects; optional

An array of BrandVersion objects for identifying the browser or similar software component. The brand and version fields are derived from the Sec-CH-UA-Full-Version-List header. For more information, see the BrandVersion object.

platform

Object; optional

The BrandVersion object for identifying the user agent's operating system. The brand value is derived from the Sec-CH-UA-Platform header, and the version value is derived from the Sec-CH-UAPlatform-Version header. For more information, see the BrandVersion object.

mobile Integer; optional

The user agent preference where:

  • 1 = The user agent prefers a mobile version of the content.

  • 0 = The user agent prefers a desktop version of the content.

This value is derived from the Sec-CH-UAMobile header.

architecture String; optional The device's major binary architecture (CPU). For example, “x86” or “arm”. This value is derived from the Sec-CH-UA-Arch header.
bitness String; optional The device bitness. For example, “64" for 64-bit architecture. This value is derived from the Sec-CH-UA-Bitness header.
model String; optional The device model. For example,"iPhone". This value is derived from the Sec-CH-UA-Model header.
source Integer; optional

The source of data used to create this object where:

  • 0 = Unspecified/unknown

  • 1 = User agent client hints. Only low-entropy headers were available.

  • 2 = User agent client hints. High-entropy headers were available.

  • 3 = Parsed from the user agent header. This is the same value in the ua field.

The default value for this field is 0.

BrandVersion object

Field Type Description

brand

String; required

The brand identifier. For example, "Windows" or "Chrome". The value may be sourced from the User-Agent Client Hints headers, representing either the user agent brand (from the Sec-CH-UA-Full-Version header) or the platform brand (from the Sec-CH-UA-Platform header).

version

Array of strings; optional

The sequence of version components, in descending hierarchical order (major, minor, micro...). For example, "14.0.0"

EID object

Field Type Description

source

String; optional

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

uids

Array of objects; optional

An array of uIDs objects from the given source. For more information, see uIDs object below.

id

String; optional

The user ID received in the request.

ext

Object; optional

The eIDs Extension object containing vendor-specific extensions. For more information, see eIDs Ext object below.

EID extension object

Field Type Description

rtipartner

String; optional

An Index optional field that specifies the name of the Universal ID provider. For example, "universalidproviderID".

UID object

Field Type Description

id

String; optional

The user ID. For example, "uid123".

ext

Object; optional

The uIDs Extension object containing vendor-specific extensions. For more information, see uIDs Ext object below.

UID extension object

Field Type Description

rtipartner

String; optional

The name of the Universal ID provider. For example, "universalidproviderID".

Data object

Field Type Description

ext

Object; optional

The data extension object that contains community extensions. See the Data Ext object.

name String; optional The unique domain of the business entity who is stating the additional information about the user or content.

segment

Array of objects; optional

Contains additional information about the related object that is specified, such as the user, site, or app object. See the Segment object.

Data extension object

Field Type Description

segtax

Integer; optional

The ID associated with a taxonomy that is registered centrally with the IAB Tech Lab.

Segment object

Field Type Description

id

String; optional

The ID that is associated with this data segment and is specific to the data provider.