Skip to main content
Categories
< All Topics
Print

Open RTB Bid Request Specifications 2.4

Suggested 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

The following objects should be sent encoded as JSON in the request body:  

Bid Request

AttributeRequired?Description
atYesAuction type, first price = 1 (int)
idYesUnique bid request ID (string)
impYesArray of Imp objects representing the impressions offered(object).
siteYesDetails via a Site object about the publisher’s website(object).
deviceYesDetails via a Device object about the user’s device to which the impression will be delivered(object).
userNoDetails via a User object about the human user of the device; the advertising audience(object).
extNoPlaceholder for extensions to OpenRTB.

imp

AttributeRequired?Description
idYesUnique impression ID within this bid request (string)
bidfloorNoMinimum bid for this impression (CPM) / click (CPC) and account currency, optional (float)
bidfloorcurNoCurrency for minimum bid value specified using ISO-4217 alpha codes, optional (string)
nativeonly for native impsA Native object ; required if this impression is offered as a native ad opportunity (object)
bannerOnly for banner impsA banner object ; required if this impression is offered as a banner ad opportunity (object)
instlOnly for instl impsAn interstitial object ; required if this impression is offered as an interstitial ad opportunity (object)
videoOnly for videoA Video object; required if this impression is offered as a video ad opportunity (object)
secureNo; Recommended 1Flag 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)
elNoBase64 Encoded Email (string)
extNoPlaceholder for exchange-specific extensions

imp.banner

AttributeRequired?Description
wYesWidth of the banner (integer)
hYesHeight of the banner (integer)

imp.instl

AttributeRequired?Description
instlYesFlag specifying if ad is popunder (integer)

imp.native (for Native and Push Notification Ads)

AttributeRequired?Description
requestYesRequest payload complying with the Native Ad Specification – a JSON encoded string of the Native Ads request including its native top level object (JSON object)
verNoVersion of the Dynamic Native Ads API to which request complies (string)

imp.native.request

AttributeRequired?Description
verYesVersion of the Native Markup version in use (string)
contextNoThe 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)
plcmttypeYesThe design/format/layout of the ad unit being offered. Currently we support 4 (Recommendation widget) and 500 (Push Notification) (integer)
plcmtcntNoThe number of identical placements in this Layout (integer)
assetsYesAn array of Asset Objects. Any bid response must comply with the array of elements expressed in the bid request (array of JSON objects)
seqNo0 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

AttributeRequired?Description
idYesUnique asset ID, assigned by exchange. Typically a counter for the array (integer) 1: Image asset ID, 2: Title asset ID, 3: Description asset ID
requiredNoSet to 1 if asset is required or 0 if asset is optional (integer)
plcmtcntNoThe number of identical placements in this Layout (integer)
imgYesImage object for image assets* (JSON object)
titleNoTitle object for title assets* (JSON object)
dataNoData object for brand name, description, ratings, prices etc.* (JSON object)
videoNoVideo 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

imp.native.request.assets.img

AttributeRequired?Description
typeNoType ID of the image element supported by the publisher. We support: 1 (Icon image) (integer), 3 (Large image preview for the ad) (integer)
wNoWidth of the image in pixels, optional (integer)
hNoHeight of the image in pixels, optional (integer)
wminYesThe minimum requested width of the image in pixels (integer)
hminYesThe minimum requested height of the image in pixels (integer)

*Push Notification icon dimensions: 192px x 192px

imp.native.request.assets.title

AttributeRequired?Description
lenYesMaximum length of the text in the title element. (integer)

imp.native.request.assets.data

AttributeRequired?Description
typeYesType 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)
lenNoMaximum length of the text in the element’s response (integer)

imp.native.request.assets.video

AttributeRequired?Description
mimesYesList of supported mime types (string array)
mindurationYesMinimum video ad duration in seconds(int).
maxdurationYesMaximum video ad duration in seconds(int).
protocolsYesList of supported video bid response protocols (int array)
linearityRequired for in-stream ads only.Indicates if the impression must be linear, nonlinear, etc. (int)
boxingallowedRequired for in-stream ads only.Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed (int)

imp.video

AttributeDescription
mimesList of supported mime types (string array)

imp.ext

AttributeRequired?Description
video_ctaNoIndicates if CTAs should be provided*

* When enabled, CTA should be provided as part of VAST Tag here.

site

AttributeRequired?Description
idRecommendedUnique Site ID (string)
domainRecommendedDomain name of the site (string)
catNoIAB category ID (string array)
pageRecommendedFull URL of the page where the ad will be shown (string)
keywordsNoKeywords can be used to ensure ad zones get the right type of advertising. Keywords should be a string of comma-separated words
extNoPlaceholder for exchange-specific extensions

site.ext

AttributeRequired?Description
exchangecatNoCustom Paradox category ID (integer)
idzoneNoCustom Paradox Ad Zone ID (integer)

device

AttributeRequired?Description
uaYesBrowser user agent (string)
geoNoLocation of the device assumed to be the user’s current location defined by a Geo object.
ipYesIP address of the user (string)*
ipv6RecommendedIPv6 address of the user (string)*
languageRecommendedBrowser language (string)
osNoOperating System (string)
jsNoSupport for JavaScript, where 0 = no, 1 = yes (integer)
extNoPlaceholder for exchange-specific extensions to OpenRTB

*Either ip or ipv6 will be in the request

device.geo

AttributeRequired?Description
countryNoCountry ISO3

device.ext

AttributeRequired?Description
remote_addrNoMain IP address of the user (string)
x_forwarded_forNoX-FORWARDED-FOR IP address of the user or empty if not set (string)

user

AttributeRequired?Description
idYes*Unique user ID (string)

Note: If you cannot generate a user ID, you can leave it empty (“”). The request will get a response as long as “user” object is included in the request.


ext

AttributeRequired?Description
subNoThe Sub ID. This should be a number between six and ten digits: Do not use zeroes at the beginning of Sub IDs.

Examples

Banner

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "at":1,
    "imp": [
        {
            "id": "974090632",
            "banner": {
                "w": 300,
                "h": 250
            }
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "keywords": "lifestyle, humour"
    },
    "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": 1221
    }
}

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",
            "bidfloor": 0.035,
            "bidfloorcur": "EUR"
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "keywords": "lifestyle, humour",
        "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": 1221
    }
}

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",
            "bidfloor": 0.035,
            "bidfloorcur": "EUR"
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "keywords": "lifestyle, humour",
        "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": 1221
    }
}

Email Clicks Bid Request Structure

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

In-Stream Video, Outstream Video, Video Slider

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "imp": [
        {
            "id": "974090632",
            "video": {
                "mimes": ["video/mp4"]
            },
            "ext": {
                "video_cta": 0
            }
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "keywords": "lifestyle, humour",
        "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": 1221
    }
}

In-Stream Video, Outstream Video, Video Slider Bid Request Structure

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

Native

{
  "id": "7a452540-c8c9-43ca-9d30-ab9d8bfd17a4",
  "at":1,
  "imp": [
    {
      "id": "2d099176-9feb-44e9-85f9-f385b34123a1",
      "native": {
        "request": "{\"native\":{\"ver\":\"1.2\"\n,\"context\":1\n,\"contextsubtype\":10\n,\"plcmttype\":4\n,\"plcmtcnt\":4\n,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":124}},{\"id\":2,\"data\":{\"type\":1,\"len\":50}},{\"id\":3,\"required\":1,\"img\":{\"type\":3,\"wmin\":150,\"hmin\":150}}]\n}}",
        "ver": "1.2"
      },
      "tagid": "2812",
      "bidfloor": 0.035,
      "secure": 1
    }
  ],
  "site": {
    "id": "2812",
    "domain": "example.com",
    "keywords": "lifestyle, humour",
    "page": "https://example.com/",
    "mobile": 1
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15G77 Version/11.4.1 Safari/604.1 AlohaBrowser/2.10.0b17",
    "ip": "88.208.2.198",
    "js": 1,
    "language": "en"
  },
  "user": {
    "id": "37d1951a-7184-4b7f-b227-5571a1ea7467"
  }
}

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
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page",
        "keywords": "lifestyle, humour"
    },
    "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": 1221
    }
}

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",
    "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"
            }
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page", 
        "keywords": "lifestyle, humour"
    },
    "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": 1221
    }
}

Push Notifications – 720 x 480 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"
            }
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page", 
        "keywords": "lifestyle, humour"
    },
    "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": 1221
    }
}

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

In-Page Push Notifications

{
    "id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
    "imp": [
        {
            "id": "90180978",
            "native": {
                "request":"{\"native\":{\"ver\":\"1.2\",\"plcmttype\":501,\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"img\":{\"type\":1}},{\"id\":2,\"required\":1,\"title\":{\"len\":60}},{\"id\":3,\"required\":1,\"data\":{\"type\":2,\"len\":110}}]}}",
                "ver": "1.2"
            }
        }
    ],
    "site": {
        "id": "12345",
        "domain": "sitedomain.com",
        "cat": ["IAB25-3"],
        "page": "https://sitedomain.com/page", 
        "keywords": "lifestyle, humour"
    },
    "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": 1221
    }
}
Table of Contents
Translate »