# Object Specification

**Object Specification: Bid Request (p. 1)**

\
The top-level bid request object contains a globally unique bid request or auction ID. This id attribute is required as is at least one impression object. Other attributes in this top-level object establish rules and restrictions that apply to all impressions being offered.

<table data-header-hidden><thead><tr><th width="128"></th><th width="261"></th><th></th></tr></thead><tbody><tr><td><strong>Attribute</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>id</td><td>string; required</td><td>Unique ID of the bid request, provided by the exchange.</td></tr><tr><td>imp</td><td>required</td><td>Representing the impressions offered. At least 1 Imp object is required.</td></tr><tr><td>site</td><td>either site or app is required</td><td>The publisher’s website.</td></tr><tr><td>app</td><td>either site or app is required</td><td>The publisher’s application (i.e., non-browser applications).</td></tr><tr><td>device</td><td>required</td><td>The user’s device to which the impression will be delivered.</td></tr><tr><td>user</td><td>optional</td><td>The human user of the device; the advertising audience.</td></tr><tr><td>at</td><td>integer; optional</td><td>Auction type, where 1 = First Price, 2 = Second Price. Default: at=2.</td></tr><tr><td>tmax</td><td>integer; optional</td><td>Maximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline if it is set up on a pub zone.</td></tr></tbody></table>

**Object Specification: Bid Request**&#x20;

| **Attribute** | **Type**     | **Description**                                                 |
| ------------- | ------------ | --------------------------------------------------------------- |
| cur           | string array | Only USD is supported.                                          |
| bcat          | string array | Blocked advertiser categories using the IAB content categories. |
| badv          | string array | Block list of advertisers by their domains (e.g., “ford.com”).  |

**Object Specification: Impression**

<table data-header-hidden><thead><tr><th width="156"></th><th width="251"></th><th></th></tr></thead><tbody><tr><td><strong>Attribute</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>id</td><td>string; required</td><td>A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).</td></tr><tr><td>banner</td><td>either banner,native or video required</td><td>A Banner object.</td></tr><tr><td>native</td><td>either banner,native or video required</td><td>A Native object.</td></tr><tr><td>video</td><td>either banner,native or video required</td><td>A Video object.</td></tr><tr><td>bidfloor</td><td>optional; float; default 0</td><td>Minimum bid for this impression expressed in CPM</td></tr><tr><td>secure</td><td>optional; integer</td><td>Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure.</td></tr></tbody></table>

**Object Specification: Banner**

<table data-header-hidden><thead><tr><th width="127"></th><th width="211"></th><th></th></tr></thead><tbody><tr><td><strong>Attribute</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>w</td><td>integer; required</td><td>Width of the impression in pixels.</td></tr><tr><td>h</td><td>integer; required</td><td>Height of the impression in pixels.</td></tr><tr><td>battr</td><td>integer array; optional</td><td>Blocked creative attributes.</td></tr><tr><td>pos</td><td>integer; optional</td><td>Ad position on screen.</td></tr><tr><td>btype</td><td>integer array; optional</td><td>Blocked banner ad types.</td></tr><tr><td>mimes</td><td>string array; optional</td><td><p>Content MIME types supported. Popular MIME types may include:</p><p>“application/x-shockwave-flash”, ”image/jpeg” and “image/gif”</p></td></tr></tbody></table>

**Object Specification: Native, User**

“Native” as an object represents a native-type impression. Native ad units are intended to blend seamlessly into the surrounding content. As such, the response must be well-structured to afford the publisher fine-grained control over rendering.

&#x20;“User” as an object contains information known or derived about the human user of the device (i.e., the audience for advertising).

<table data-header-hidden><thead><tr><th width="121"></th><th width="108"></th><th width="198"></th><th></th></tr></thead><tbody><tr><td><strong>Object</strong></td><td><strong>Attribute</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>Native</td><td>request</td><td>required</td><td>Request payload complying with the Native Ad Specification as a string.</td></tr><tr><td>Native</td><td>battr</td><td>integer array; optional</td><td>Blocked creative attributes.</td></tr><tr><td>User</td><td>id</td><td>string; optional</td><td>Exchange-specific ID for the user.</td></tr><tr><td>User</td><td>buyeruid</td><td>string; optional</td><td>Buyer-specific ID for the user as mapped by the exchange for the buyer.</td></tr><tr><td>User</td><td>yob</td><td>string; optional</td><td>Year of birth as a 4-digit integer.</td></tr></tbody></table>

**Native Request Markup Object**

Native request Markup is an escaped JSON document that should be included to a Native Object’s attribute - request. “User” as an object contains information known or derived about the human user of the device (i.e., the audience for advertising). The Default column dictates how optional parameters should be interpreted if explicit values are not provided.&#x20;

<table data-header-hidden><thead><tr><th width="120"></th><th width="145"></th><th width="131"></th><th width="88"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Scope</strong></td><td><strong>Type</strong></td><td><strong>Default</strong></td><td><strong>Description</strong></td></tr><tr><td>ver</td><td>optional</td><td>string</td><td>1</td><td>Version of the Native Markup version in use.</td></tr><tr><td>layout</td><td>recommended</td><td>integer</td><td>-</td><td>The Layout ID of the native ad unit.</td></tr><tr><td>adunit</td><td>recommended</td><td>integer</td><td>-</td><td>The Ad unit ID of the native ad unit.</td></tr><tr><td>plcmtcnt</td><td>optional</td><td>integer</td><td>1</td><td>The number of identical placements in this Layout.</td></tr><tr><td>seq</td><td>optional</td><td>integer</td><td>0</td><td>0 for the first ad, 1 for the second ad, and so on.</td></tr><tr><td>assets</td><td>optional</td><td><p>an array of</p><p>Asset Objects</p><p><br></p></td><td>-</td><td>Any bid must comply with the array of elements expressed by the Exchange.</td></tr></tbody></table>

**Object Specification: Site**

\
This object should be included if the ad-supported content is a website as opposed to a non-browser application.

<table data-header-hidden><thead><tr><th width="157"></th><th width="215"></th><th></th></tr></thead><tbody><tr><td><strong>Attribute</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>pagecat</td><td>string array; optional</td><td>Array of IAB content categories that describe the current page or view of the site.</td></tr><tr><td>domain</td><td>string; optional</td><td>Domain of the site (e.g., “mysite.foo.com”).</td></tr><tr><td>page</td><td>string; optional</td><td>URL of the page where the impression will be shown.</td></tr><tr><td>cat</td><td>string array; optional</td><td>Array of IAB content categories of the site.</td></tr><tr><td>sectioncat</td><td>string array; optional</td><td>Array of IAB content categories that describe the current section of the site.</td></tr></tbody></table>

**App Object**

\
This object should be included if the ad-supported content is a non-browser application (typically in mobile) as opposed to a website.

<table data-header-hidden><thead><tr><th width="149"></th><th width="206"></th><th></th></tr></thead><tbody><tr><td><strong>Attribute</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>id</td><td>string; optional</td><td>Exchange-specific app ID.</td></tr><tr><td>name</td><td>string; optional</td><td>App name (may be aliased at the publisher’s request)</td></tr><tr><td>bundle</td><td>string; required</td><td>Application bundle or package name (e.g., com.foo.mygame for Android apps and 123456 for Apple apps).</td></tr><tr><td>domain</td><td>string; optional</td><td>Domain of the app (e.g., “mygame.foo.com”).</td></tr><tr><td>storeurl</td><td>string; optional</td><td>App store URL for an installed app.</td></tr><tr><td>cat</td><td>string array; optional</td><td>Array of IAB content categories of the app.</td></tr><tr><td>sectioncat</td><td>string array; optional</td><td>Array of IAB content categories that describe the current section of the app.</td></tr><tr><td>pagecat</td><td>string array; optional</td><td>Array of IAB content categories that describe the current page or view of the app.</td></tr></tbody></table>

This object should be included if the ad-supported content is a non-browser application (typically in mobile) as opposed to a website.

<table data-header-hidden><thead><tr><th width="149"></th><th width="157"></th><th></th></tr></thead><tbody><tr><td><strong>Attribute</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>ver</td><td>string; optional</td><td>Application version.</td></tr><tr><td>privacypolicy</td><td>integer; optional</td><td>Indicates if the app has a privacy policy, where 0 = no, 1 = yes.</td></tr><tr><td>paid</td><td>integer; optional</td><td>0 = app is free, 1 = the app is a paid version.</td></tr><tr><td>keywords</td><td>string; optional</td><td>Comma separated list of keywords about the app.</td></tr></tbody></table>

**Device Object**

This object provides information pertaining to the device through which the user is interacting. Device information includes its hardware, platform, location, and carrier data. The device can refer to a mobile handset, a desktop computer, set-top box, or other digital device. For desktop devices only “ua” and “ip” attributes are required. Mobile devices require “ifa” or “ifa” hashes to be present.

<table data-header-hidden><thead><tr><th width="150"></th><th width="154"></th><th></th></tr></thead><tbody><tr><td><strong>Attribute</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>ua</td><td>string; optional</td><td>Browser user agent string.</td></tr><tr><td>geo</td><td>integer; optional</td><td>Location of the device assumed to be the user’s current location defined by a Geo object.</td></tr><tr><td>ip</td><td>integer; optional</td><td>IPv4 address.</td></tr><tr><td>devicetype</td><td>string; optional</td><td>The general type of device.</td></tr><tr><td>make</td><td>string; optional</td><td>Device make (e.g., “Apple”).</td></tr><tr><td>model</td><td>string; optional</td><td>Device model (e.g., “iPhone”).</td></tr><tr><td>os</td><td>string; optional</td><td>Device operating system (e.g., “iOS”).</td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="151"></th><th width="154"></th><th></th></tr></thead><tbody><tr><td>hwv</td><td>string; optional</td><td>Hardware version of the device (e.g., “5S” for iPhone 5S).</td></tr><tr><td>h</td><td>integer; optional</td><td>Physical height of the screen in pixels.</td></tr><tr><td>w</td><td>integer; optional</td><td>Physical width of the screen in pixels.</td></tr><tr><td>ppi</td><td>integer; optional</td><td>Screen size as pixels per linear inch.</td></tr><tr><td>pxratio</td><td>float; optional</td><td>The ratio of physical pixels to device independent pixels.</td></tr><tr><td>flashver</td><td>string; optional</td><td>Version of Flash supported by the browser.</td></tr><tr><td>language</td><td>string; optional</td><td>Browser language using ISO-639-1-alpha-2.</td></tr><tr><td>carrier</td><td>string; optional</td><td>Carrier or ISP (e.g., “VERIZON”). “WIFI” is often used in mobile to indicate high bandwidth.</td></tr><tr><td>connectiontype</td><td>integer; optional</td><td>Network connection type.</td></tr><tr><td>js</td><td>integer; optional</td><td>Support for JavaScript, where 0 = no, 1 = yes.</td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="151"></th><th width="159"></th><th></th></tr></thead><tbody><tr><td>ifa</td><td>string; at least 1 must be present; optional</td><td>ID sanctioned for advertiser use in the clear (i.e., not hashed). “Apple ID for Advertising” or “Android Advertiser Id”.</td></tr><tr><td>didsha1</td><td>string; at least 1 must be present; optional</td><td>Hardware device ID (e.g., IMEI); hashed via SHA1.</td></tr><tr><td>didmd5</td><td>string; at least 1 must be present; optional</td><td>Hardware device ID (e.g., IMEI); hashed via MD5.</td></tr><tr><td>dpidsha1</td><td>string; at least 1 must be present; optional</td><td>Platform device ID (e.g., Android ID); hashed via SHA1.</td></tr><tr><td>dpidmd5</td><td>string; at least 1 must be present; optional</td><td>Platform device ID (e.g., Android ID); hashed via MD5.</td></tr><tr><td>macsha1</td><td>string; optional</td><td>MAC address of the device; hashed via SHA1.</td></tr><tr><td>macmd5</td><td>string; optional</td><td>MAC address of the device; hashed via MD5.</td></tr></tbody></table>

**Geo Object**&#x20;

This object encapsulates various methods for specifying a geographic location.

<table data-header-hidden><thead><tr><th width="124"></th><th width="158"></th><th></th></tr></thead><tbody><tr><td><strong>Attribute</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>lat</td><td>float; optional</td><td>Latitude from -90.0 to +90.0, where negative is south.</td></tr><tr><td>lon</td><td>float; optional</td><td>Longitude from -180.0 to +180.0, where negative is west.</td></tr><tr><td>type</td><td>integer; optional</td><td>Source of location data; recommended when passing lat/lon. type=1: GPS/Location Services, type=2: IP Address, type=3: User provided (e.g., registration data).</td></tr><tr><td>country</td><td>string; optional</td><td>Country code using ISO-3166-1-alpha-3.</td></tr><tr><td>region</td><td>string; optional</td><td>Region code using ISO-3166-2; 2-letter state code if USA.</td></tr><tr><td>city</td><td>string; optional</td><td>City from MaxMind geo database.</td></tr><tr><td>zip</td><td>string; optional</td><td>Zip or postal code.</td></tr><tr><td>utcoffset</td><td>string; optional</td><td>Local time as the number +/- of minutes from UTC.</td></tr></tbody></table>

**Asset Object**

\
The main container object for each asset requested or supported by Exchange on behalf of the rendering client. Any object that is required is to be flagged as such. Only one of the {title, image, data, video} objects should be present in each object. All others should be null/absent. The id is to be unique within the Asset Object array so that the response can be aligned.

&#x20;

<table data-header-hidden><thead><tr><th width="109"></th><th width="130"></th><th width="115"></th><th width="89"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Scope</strong></td><td><strong>Type</strong></td><td><strong>Default</strong></td><td><strong>Description</strong></td></tr><tr><td>id</td><td>required</td><td>integer</td><td>-</td><td><p>Unique asset ID, assigned by exchange. Typically a counter for the</p><p>array.</p></td></tr><tr><td>required</td><td>optional</td><td>integer</td><td>0</td><td><p>Set to 1 if asset is required (exchange will not accept a bid</p><p>without it).</p></td></tr><tr><td>title</td><td><p>one of the</p><p>{title, img,</p><p>data, video}<br></p></td><td>object</td><td>-</td><td>Title object for title assets.</td></tr><tr><td>data</td><td><p>one of the</p><p>{title, img,</p><p>data, video}</p></td><td>object</td><td>-</td><td>Data object for ratings, prices etc.</td></tr><tr><td>img</td><td><p>one of the</p><p>{title, img,</p><p>data, video}</p></td><td>object</td><td>-</td><td>Image object for image assets.</td></tr><tr><td>video</td><td><p>one of the</p><p>{title, img,</p><p>data, video}</p></td><td>object</td><td></td><td>Video object for video assets.</td></tr></tbody></table>

**Title Object**

The Title object is to be used for the title element of the Native ad.

<table data-header-hidden><thead><tr><th width="103"></th><th width="112"></th><th width="101"></th><th width="96"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Scope</strong></td><td><strong>Type</strong></td><td><strong>Default</strong></td><td><strong>Description</strong></td></tr><tr><td>len</td><td>required</td><td>integer</td><td>-</td><td>Maximum length of the text in the title element.</td></tr></tbody></table>

**Image Asset Object**

<table data-header-hidden><thead><tr><th width="111"></th><th width="144"></th><th width="117"></th><th width="116"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Scope</strong></td><td><strong>Type</strong></td><td><strong>Default</strong></td><td><strong>Description</strong></td></tr><tr><td>type</td><td>optional</td><td>integer</td><td>-</td><td>Type ID of the image element supported by the publisher.</td></tr><tr><td>w</td><td>optional</td><td>integer</td><td>-</td><td>Width of the image in pixels.</td></tr><tr><td>wmin</td><td>recommended</td><td>integer</td><td>-</td><td>The minimum requested width of the image in pixels.</td></tr><tr><td>h</td><td>optional</td><td>integer</td><td>-</td><td>Height of the image in pixels.</td></tr><tr><td>hmin</td><td>recommended</td><td>integer</td><td>-</td><td>The minimum requested height of the image in pixels.</td></tr><tr><td>mimes</td><td>optional</td><td>array of strings</td><td>All types allowed</td><td><p>Whitelist of content MIME types supported. Popular MIME types</p><p>include, but are not limited to “image/jpg” “image/gif”.</p></td></tr></tbody></table>

**Video Asset Object**

The video object to be used for all video elements supported in the Native Ad.

<table data-header-hidden><thead><tr><th width="146"></th><th width="118"></th><th width="142"></th><th width="103"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Scope</strong></td><td><strong>Type</strong></td><td><strong>Default</strong></td><td><strong>Description</strong></td></tr><tr><td>mimes</td><td>required</td><td>array of strings</td><td>-</td><td>Content MIME types supported. Popular MIME types include,but are not limited to “video/x-ms-wmv” for Windows Media, and “video/x-flv” for Flash Video.</td></tr><tr><td>minduration</td><td>required</td><td>integer</td><td>-</td><td>Minimum video ad duration in seconds.</td></tr><tr><td>maxduration</td><td>required</td><td>integer</td><td>-</td><td>Maximum video ad duration in seconds.</td></tr><tr><td>protocols</td><td>required</td><td>array of integers</td><td>-</td><td>An array of video protocols the publisher can accept in the bid response.</td></tr></tbody></table>

**Data Asset Object**

<table data-header-hidden><thead><tr><th width="111"></th><th width="121"></th><th width="93"></th><th width="96"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td>Scope</td><td><strong>Type</strong></td><td><strong>Default</strong></td><td><strong>Description</strong></td></tr><tr><td>type</td><td>required</td><td>integer</td><td>-</td><td>Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format.</td></tr><tr><td>len</td><td>optional</td><td>integer</td><td>-</td><td><p>Maximum length of the text in the element’s response.</p><p><br></p></td></tr></tbody></table>