Open RTB Bid Request Specifications

Bid Request Headers

• OpenRTB Version HTTP Header: x-openrtb-version: 2.4
• Keep-Alive HTTP Header: Connection: Keep-Alive
• Content JSON: Content-Type: application/json
• Data Encoding Header: Accept-Encoding

Bid Request

When requesting bids for a specific context, the platform will perform an HTTP request with a timeout of 300ms and send the following object encoded as JSON in the request body. HTTP is recommended due to extra latency when using HTTPS.  

Attribute	Description
at	Auction type, first price = 1 (int)
id	Unique bid request ID (string)
imp	Array of Imp objects representing the impressions offered(object).
site	Details via a Site object about the publisher’s website(object).
device	Details via a Device object about the user’s device to which the impression will be delivered(object).
user	Details via a User object about the human user of the device; the advertising audience(object).
ext	Placeholder for extensions to OpenRTB.

 

imp

Attribute	Description
id	Unique impression ID within this bid request (string)
bidfloor	Minimum bid for this impression expressed in CPM, optional (float)
bidfloorcur	Currency for minimum bid value specified using ISO-4217 alpha codes, optional (string)
native	A Native object ; required if this impression is offered as a native ad opportunity(object).
banner	A banner object ; required if this impression is offered as a banner ad opportunity(object).
instl	An interstitial object ; required if this impression is offered as an interstitial ad opportunity(object).
secure	Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP support can be assumed, optional (integer)
el	Base64 Encoded Email (string)

 

imp.banner

Attribute	Description
w	Width of the banner in pixels (integer).
h	Height of the banner in pixels (integer).

 

imp.ext

Attribute	Description
interstitial	Identify Fullpage Interstitial ad type (integer). 1=interstitial.

 

imp.instl

Attribute	Description
instl	Flag specifying if ad is popunder/interstitial (integer): 1=true, 0=false

 

imp.native (Native & Push Notifications)

Attribute	Description
request	Request payload complying with the Native Ad Specification - a JSON encoded string of the Native Ads request including its native top level object (JSON object)
ver	Version of the Dynamic Native Ads API to which request complies (string)

 

imp.native.request

Attribute	Description
ver	Version of the Native Markup version in use (string)
context	The context in which the ad appears. In this case it is 1 (Content-centric context such as newsfeed, article, image gallery, video gallery, or similar), optional (integer)
plcmttype	The design/format/layout of the ad unit being offered. Currently we support 4 (Recommendation widget) and 500 (Push Notification) (integer)
plcmtcnt	The number of identical placements in this Layout (integer)
assets	An array of Asset Objects. Any bid response must comply with the array of elements expressed in the bid request (array of JSON objects)
seq	0 for the first ad, 1 for the second ad, and so on. Note this would generally NOT be used in combination with plcmtcnt - either you are auctioning multiple identical placements (in which case plcmtcnt>1, seq=0) or you are holding separate auctions for distinct items in the feed (in which case plcmtcnt=1, seq=>=1)

 

imp.native.request.assets

Attribute	Description
id	Unique asset ID, assigned by exchange. Typically a counter for the array (integer)
required	Set to 1 if asset is required or 0 if asset is optional** (integer)
plcmtcnt	The number of identical placements in this Layout (integer)
img	Image object for image assets* (JSON object)
title	Title object for title assets* (JSON object)
data	Data object for brand name, description, ratings, prices etc.* (JSON object)
video	Video object for video assets. See the Video request object definition. Note that in-stream (ie preroll, etc) video ads are not part of Native. Native ads may contain a video as the ad creative itself(object).

* Only one of the {img, title, data} objects should be present in each asset object

** Assets are flagged as required according to the configuration of the publisher zone where your ad may be displayed

 

imp.native.request.assets.img

Attribute	Description
type	Type ID of the image element supported by the publisher. We support: 1 (Icon image) (integer), 3 (Large image preview for the ad) (integer)
w	Width of the image in pixels, optional (integer)
h	Height of the image in pixels, optional (integer)
wmin	The minimum requested width of the image in pixels (integer)
hmin	The minimum requested height of the image in pixels (integer)

 

imp.native.request.assets.title

Attribute	Description
len	Maximum length of the text in the title element. (integer)

 

imp.native.request.assets.data

Attribute	Description
type	Type ID of the element supported by the publisher (integer). We support: 1 (sponsored - Sponsored By message where response should contain the brand name of the sponsor), 2 (desc - Descriptive text associated with the product or service being advertised)
len	Maximum length of the text in the element’s response (integer)

 

imp.native.request.assets.video

Attribute	Description
mimes	List of supported mime types (string array)
minduration	Minimum video ad duration in seconds(int).
maxduration	Maximum video ad duration in seconds(int).
protocols	List of supported video bid response protocols (int array)
linearity	Indicates if the impression must be linear, nonlinear, etc. (int)
boxingallowed	Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed (int)

 

imp.video

Attribute	Description
mimes	List of supported mime types (string array)
protocols	List of supported video bid response protocols (int array)
linearity	Indicates if the impression must be linear, nonlinear, etc. (int)
boxingallowed	Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed (int)

 

site

Attribute	Description
id	Unique Site ID (string)
domain	Domain name of the site (string)
cat	IAB category ID (string array)
page	Full URL of the page where the ad will be shown (string)
keywords	Keywords can be used to ensure ad zones get the right type of advertising. Keywords should be a string of comma-separated words
ext	Placeholder for exchange-specific extensions

 

site.ext

Attribute	Description
exchangecat	Custom Adnation category ID (integer)
idzone	Custom Adnation Ad Zone ID (integer)
keyword	Matching keyword if any (string)

 

device

Attribute	Description
ua	Browser user agent (string)
geo	Location of the device assumed to be the user’s current location defined by a Geo object.
ip	IP address of the user (string)*
ipv6	IPv6 address of the user (string)*
language	Browser language using ISO-639-1-alpha-2 (string)
os	Operating System (string)
js	Support for JavaScript, where 0 = no, 1 = yes (integer)
ext	Placeholder for exchange-specific extensions to OpenRTB

 

device.geo

Attribute	Description
country	Country ISO3

 

device.ext

Attribute	Description
remote_addr	Main IP address of the user (string)
x_forwarded_for	X-FORWARDED-FOR IP address of the user or empty if not set (string)

 

user

Attribute	Description
id	Unique user ID (string)

 

ext

Attribute	Required?	Description
sub	No	The sub will be an integer number representing the ID of the zone where the request was originated from.

 

Examples

Banner

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "at":1,
    "imp": [
        {
            "id": "6145298465",
            "instl": 0,
            "banner": {
                "w": 300,
                "h": 250
            },
            "bidfloor": 0.5,
            "bidfloorcur": "USD",
            "secure": 1
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "ext": {
            "exchangecat": 508,
            "idzone": 445566
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "ip": "131.34.123.159",
        "geo": {
            "country": "IRL"
        },
        "language": "en",
        "os": "Linux & UNIX",
        "js": 0,
        "ext": {
            "remote_addr": "131.34.123.159",
            "x_forwarded_for": "",
            "accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
        }
    },
    "user": {
        "id": "57592f333f8983.043587162282415065"
    },
    "ext": {
        "sub": 445566
    }
}

 

Banner Bid Request Structure

• imp
  • imp.banner
• site
  • site.ext
• device
  • device.geo
  • device.ext
• user

 

Direct Links

JSON

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "imp": [
        {
            "id": "974090632",
            "instl": 0,
            "el": "dGVzdGVAZW1haWwuY29t"
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "ext": {
            "exchangecat": 508,
            "idzone": 445566
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "ip": "192.168.1.70",
        "geo": {
            "country": "PRT"
        },
        "language": "en",
        "os": "Linux & UNIX",
        "js": 0,
        "ext": {
            "remote_addr": "192.168.1.70",
            "x_forwarded_for": "192.168.1.70"
        }
    },
    "user": {
        "id": "57592f333f8983.043587162282415065"
    },
    "ext": {
        "sub": 445566
    }    
}

 

Direct Links Bid Request Structure

• imp
  • imp.instl
• site
  • site.ext
• device
  • device.geo
  • device.ext
• user

 

Email Clicks

JSON

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "imp": [
        {
            "id": "974090632",
            "instl": 0,
            "el": "dGVzdGVAZW1haWwuY29t"
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "ext": {
            "exchangecat": 508,
            "idzone": 445566
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "ip": "192.168.1.70",
        "geo": {
            "country": "PRT"
        },
        "language": "en",
        "os": "Linux & UNIX",
        "js": 0,
        "ext": {
            "remote_addr": "192.168.1.70",
            "x_forwarded_for": "192.168.1.70"
        }
    },
    "user": {
        "id": "57592f333f8983.043587162282415065"
    },
    "ext": {
        "sub": 445566
    }    
}

 

Email Clicks Bid Request Structure

• imp
  • imp.instl
• site
  • site.ext
• device
  • device.geo
  • device.ext
• user

 

Fullpage Interstitial (Mobile and Desktop)

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "at":1,
    "imp": [
        {
            "id": "974090632",
            "instl": 1
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "ext": {
            "exchangecat": 508,
            "idzone": 445566
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "ip": "120.52.73.97",
        "geo": {
            "country": "IRL"
        },
        "language": "en",
        "os": "Linux & UNIX",
        "js": 0,
        "ext": {
            "remote_addr": "131.34.123.159",
            "x_forwarded_for": "120.52.73.97"
        }
    },
    "user": {
        "id": "57592f333f8983.043587162282415065"
    },
    "ext": {
        "sub": 445566
    }
}

 

Fullpage Interstitial (Mobile and Desktop) Bid Request Structure

• imp
  • imp.instl
• site
  • site.ext
• device
  • device.geo
  • device.ext
• user

 

In-Stream

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "at":1,
    "imp": [
        {
            "id": "43389012",
            "video": {
                "mimes": [
                    "video/mp4"
                ],
                "protocols": [
                    3,
                    6
                ],
                "linearity": 1,
                "boxingallowed": 1
            },
            "bidfloor": 0.5,
            "bidfloorcur": "USD",
            "secure": 1
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "ext": {
            "exchangecat": 508,
            "idzone": 445566
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "ip": "131.34.123.159",
        "geo": {
            "country": "IRL"
        },
        "language": "en",
        "os": "Linux & UNIX",
        "js": 0,
        "ext": {
            "remote_addr": "131.34.123.159",
            "x_forwarded_for": "",
            "accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
        }
    },
    "user": {
        "id": "57592f333f8983.043587162282415065"
    },
    "ext": {
        "sub": 445566
    }
}

 

In-Stream Bid Request Structure

• imp
  • imp.video
• site
  • site.ext
• device
  • device.geo
  • device.ext
• user

 

Native

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "at":1,
    "imp": [
        {
            "id": "90180978",
            "native": {
                "request":"{\"native\":{\"ver\":\"1.2\",\"context\":1,\"plcmttype\":4,\"plcmtcnt\":5,\"assets\":[{\"id\":1,\"required\":1,\"img\":{\"type\":3,\"wmin\":100,\"hmin\":100}},{\"id\":2,\"required\":1,\"title\":{\"len\":60}},{\"id\":3,\"required\":1,\"data\":{\"type\":2,\"len\":110}},{\"id\":4,\"required\":1,\"data\":{\"type\":1,\"len\":110}}]}}",
                "ver": "1.2"
            },
            "secure": 1
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "ext": {
            "exchangecat": 508,
            "idzone": 445566
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "ip": "131.34.123.159",
        "geo": {
            "country": "IRL"
        },
        "language": "en",
        "os": "Linux & UNIX",
        "js": 0,
        "ext": {
            "remote_addr": "131.34.123.159",
            "x_forwarded_for": "",
            "accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
        }
    },
    "user": {
        "id": "57592f333f8983.043587162282415065"
    },
    "ext": {
        "sub": 445566
    }
}

 

Native Bid Request Structure

• imp
  • imp.native
    • imp.native.request
      • imp.native.request.assets
        • imp.native.request.assets.img
        • imp.native.request.assets.title
        • imp.native.request.assets.data
        • imp.native.request.assets.video
• site
  • site.ext
• device
  • device.geo
  • device.ext
• user

 

Popunder

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "at":1,
    "imp": [
        {
            "id": "974090632",
            "instl": 1,
            "bidfloor": 0.5,
            "bidfloorcur": "USD",
            "secure": 1
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "ext": {
            "exchangecat": 508,
            "idzone": 445566
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "ip": "120.52.73.97",
        "geo": {
            "country": "IRL"
        },
        "language": "en",
        "os": "Linux & UNIX",
        "js": 0,
        "ext": {
            "remote_addr": "131.34.123.159",
            "x_forwarded_for": "120.52.73.97",
            "accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
        }
    },
    "user": {
        "id": "57592f333f8983.043587162282415065"
    },
    "ext": {
        "sub": 445566
    }
}

 

Popunder Bid Request Structure

• imp
  • imp.instl
• site
  • site.ext
• device
  • device.geo
  • device.ext
• user

 

Push Notifications - 720 x 480

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "at":1,
    "imp": [
        {
            "id": "90180978",
            "native": {
                "request":"{\"native\":{\"ver\":\"1.2\",\"plcmttype\":500,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"img\":{\"type\":1,\"w\":720,\"h\":480,\"wmin\":720,\"hmin\":480}},{\"id\":2,\"required\":1,\"title\":{\"len\":60}},{\"id\":3,\"required\":1,\"data\":{\"type\":2,\"len\":110}}]}}",
                "ver": "1.2"
            },
            "secure": 1
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "ext": {
            "exchangecat": 508,
            "idzone": 445566
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "ip": "131.34.123.159",
        "geo": {
            "country": "IRL"
        },
        "language": "en",
        "os": "Linux & UNIX",
        "js": 0,
        "ext": {
            "remote_addr": "131.34.123.159",
            "x_forwarded_for": "",
            "accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
        }
    },
    "user": {
        "id": "57592f333f8983.043587162282415065"
    },
    "ext": {
        "sub": 445566
    }
}

 

Push Notifications 720x480 Bid Request Structure

• imp
  • imp.native
    • imp.native.request
      • imp.native.request.assets
        • imp.native.request.assets.img
        • imp.native.request.assets.title
        • imp.native.request.assets.data
        • imp.native.request.assets.video
• site
  • site.ext
• device
  • device.geo
  • device.ext
• user

 

Push Notifications - 192 x 192

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "at":1,
    "imp": [
        {
            "id": "90180978",
            "native": {
                "request":"{\"native\":{\"ver\":\"1.2\",\"plcmttype\":500,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"img\":{\"type\":1,\"w\":192,\"h\":192,\"wmin\":192,\"hmin\":192}},{\"id\":2,\"required\":1,\"title\":{\"len\":60}},{\"id\":3,\"required\":1,\"data\":{\"type\":2,\"len\":110}}]}}",
                "ver": "1.2"
            },
            "secure": 1
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "ext": {
            "exchangecat": 508,
            "idzone": 445566
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.63 Safari/537.36",
        "ip": "131.34.123.159",
        "geo": {
            "country": "IRL"
        },
        "language": "en",
        "os": "Linux & UNIX",
        "js": 0,
        "ext": {
            "remote_addr": "131.34.123.159",
            "x_forwarded_for": "",
            "accept_language": "en-GB;q=0.8,pt-PT;q=0.6,en;q=0.4,en-US;q=0.2,de;q=0.2,es;q=0.2,fr;q=0.2"
        }
    },
    "user": {
        "id": "57592f333f8983.043587162282415065"
    },
    "ext": {
        "sub": 445566
    }
}

 

Push Notifications - 192 x 192 Bid Request Structure

• imp
  • imp.native
    • imp.native.request
      • imp.native.request.assets
        • imp.native.request.assets.img
        • imp.native.request.assets.title
        • imp.native.request.assets.data
        • imp.native.request.assets.video
• site
  • site.ext
• device
  • device.geo
  • device.ext
• user