Open RTB Bid Response Specifications
The response for a bid request will have the following structure:
Bid Response Object
| Attribute | Required? | Description |
|---|---|---|
| id | Yes | ID of the bid request (string) |
| seatbid | Yes | Collection of bids made by the bidder on behalf of a specific seat. |
seatbid
| Attribute | Required? | Description |
|---|---|---|
| bid | Yes | ID of the impression object to which this bid applies (string) |
seatbid.bid
| Attribute | Required? | Description |
|---|---|---|
| id | Yes | ID for the bid object chosen by the bidder (string) |
| impid | Yes | ID of the impression object to which this bid applies (string) |
| price | Yes | Bid price in CPM or CPC (float) |
| adm | Yes | Adnation XML/JSON Ad Markup (string) |
| nurl | Yes* | Win notification URL, it is recommended to use HTTP over HTTPS for nurl (string) |
| cid | No | Campaign ID to assist with ad quality checking (string) |
| crid | No | Creative ID to assist with ad quality checking (string) |
| ext | No | Adnation specific extension (object) |
Note: The nURL must be notified in order to ensure campaign capping and avoid getting the same response every time.
seatbid.bid.ext
| Attribute | Required? | Description |
|---|---|---|
| btype | Recommended | Pricing Model. Values: 1 = CPM, 2 = CPC. Default = 1 (int). Note: When response is for an Email Clicks zone request, 1 = Smart CPC. |
Note: Only Push Notification and Native ad formats may bid with the CPC pricing model.
JSON Examples
Banner / iFrame / Popunder / In-Stream / Push Notifications: JSON
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"seatbid": [{
"bid": [{
"id": "12ab3d",
"impid": "974090632",
"price": 0.55,
"adm": "<Adnation_XML_OR_JSON_AD_MARKUP>",
"nurl": "http://network-domain.com/win-notification",
"cid" : "123456",
"crid" : "22334455",
"ext": {
"btype": 1
}
}]
}]
}
Direct Links: JSON
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"seatbid": [
{
"bid": [
{
"id": "9093b7bc2715a39446fe380ecb63a45a96485cd8",
"impid": "974090632",
"price": 0.07,
"adm": "<Adnation_XML_AD_MARKUP>",
"ext": {
"btype": 2
},
"nurl": "https://mysite.com/my_notification_url",
"cid" : "123456",
"crid" : "22334455"
}
]
}
]
}
Email Clicks: JSON
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"seatbid": [
{
"bid": [
{
"id": "9093b7bc2715a39446fe380ecb63a45a96485cd8",
"impid": "974090632",
"price": 0.07,
"adm": "<Adnation_XML_AD_MARKUP>",
"ext": {
"btype": 2
},
"nurl": "https://mysite.com/my_notification_url",
"cid" : "123456",
"crid" : "22334455"
}
]
}
]
}
In-Stream Video, Outstream Video, Video Slider
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"seatbid": [
{
"bid": [
{
"id": "7717e2c2a243da65144d9c0abe8b46bb775c587f",
"impid": "974090632",
"price": 0.008488200000000001,
"adm": "<Adnation_XML_AD_MARKUP>",
"nurl": "http://mysite.com/my_notification_url?zid=4286963&data=TVRZeU1UVTVOVE0yTlh3ek16ZGpPRGcwWVRrek1UTTRZak5rTkdGaFl6STJaRFkwT1RBeU9ESTNNZy0tfDIwMjEtMDUtMjEgMDc6MDk6MjV8MTAuNDIuMC4xfFhYWHw0MXx6ZXJvcGFyay5jb218MTk1NjAwfDQzMjQzN3w2NDUwNjd8NDI4Njk2M3w1MTF8NDQ0MDE0MXw1Mzc4MTI0NXwxNXwyfDB8MHwwfDEyMjF8MHwwfFVTRHxFVVJ8MS4yMTI2fDEuMjEyNnwzOXx8MXxYWFh8MTkyLjE2OC4xLjcwfDMwfDR8MXx8NTc1OTJmMzMzZjg5ODMuMDQzNTg3MTYyMjgyNDE1MDY1fDY1NThjNGRmYjM5NTdhOTk0NTg0NmMzY2MzMTExZmNjfHNpdGVkb21haW4uY29tfDB8MHwwfDB8ZDRiNWM2OTctNDFmMy00YzFjLWEzZDUtNWZkMDFiNWVmMmFhfDB8MTMwfDB8V0lOTkVSfHwxfDAuMDEyMTI2fDB8MHwyfDB8MHwwfDB8LTF8MHwwfHx8fDB8MHwwfHx8fDUxfDB8MHwxfE9LfDEzZTBlZTU0OWI0NmIzNmE4NTg3NWVlNTAyMWYzMmQx",
"cid" : "123456",
"crid" : "22334455"
}
]
}
]
}
Native: JSON
{
"id": "7a452540-c8c9-43ca-9d30-ab9d8bfd17a4",
"seatbid":
[
{
"bid":
[
{
"id": "4fab7972833e2aaf53a828b1408fc104293734e3",
"impid": "2d099176-9feb-44e9-85f9-f385b34123a1",
"price":0.0025,
"adm": "<Adnation_JSON_AD_MARKUP>",
"ext": { "btype": 1 },
"nurl": "https://mysite.com/my_notification_url",
"cid" : "123456",
"crid" : "22334455"
}
]
}
]
}
ADM Examples
Banner: XML (img banner)
<?xml version="1.0" encoding="ISO-8859-1"?>
<ad>
<imageAd>
<clickUrl><![CDATA[http://mysite.com/landingpages/mypage]]></clickUrl>
<imgUrl><![CDATA[http://mysite.com/images/myad.jpg]]></imgUrl>
</imageAd>
</ad>
Banner: XML (video banner)
<?xml version="1.0" encoding="ISO-8859-1"?>
<ad>
<videoAd>
<clickUrl><![CDATA[http://mysite.com/landingpages/mypage]]></clickUrl>
<videoUrl><![CDATA[http://mysite.com/videos/myad.mp4]]></imgUrl>
</videoAd>
</ad>
Banner: HTML (img banner)
<a href=\"https:\/\/mysite.com\/click.php?data=H4sIAAAAA...8Da8a74VIAQAA\" target=\"_blank\" ontouchstart=\"\" onclick=\"var href='https:\/\/mysite.com\/click.php?data=H4sIAAAAA...8Da8a74VIAQAA'; this.href = href + '&clickX=' + event.clientX + '&clickY=' + event.clientY;\"><img width=\"300\" height=\"250\" src=\"https:\/\/static.exads.rocks\/library\/432437\/7fed7f2794236bc6544da662be1368a1f5d73e91.jpg\" border=\"0px\" style=\"\"><\/a><img src=\"https:\/\/mysite.com\/cimp.php?data=TVRZM056UTVOak...2Y1Yw--\" width=\"1\" height=\"1\" border=\"0\" \/>
Banner: HTML (video banner)
<a href=\"https://mysite.com\/click.php?data=H4sIAAAAAAAAAz1Pu27DMAz8FS...ffdr\" target=\"_blank\" ontouchstart=\"\" onclick=\"var href='https://mysite.com\/click.php?data=H4sIAAAAAAAAAz1Pu27DMAz8FS...ffdr'; this.href = href + '&clickX=' + event.clientX + '&clickY=' + event.clientY;\"><video playsinline autoplay loop=\"true\" muted=\"true\" preload=\"auto\" width=\"300\" height=\"250\" src=\"https:\/\/static.exads.rocks\/library\/432437\/c4e06d9622aa2e1799adfeed62ca6d1eebc73e9b.mp4\"><source src=\"https:\/\/mysite.com\/library\/111437\/c4e06d9622aa2e1799adfeed62ca6d1eebc73e9b.mp4\" type=\"video\/mp4\"><\/video><\/a><img src=\"https:\/\/syndication.{examplenetworkdomain}\/cimp.php?data=TVR...mQ1MzQ2OTUzYzg-\" width=\"1\" height=\"1\" border=\"0\" \/>
Direct Links: XML
<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>
<ad>
<emailClick>
<url><![CDATA[https://mysite.com/landingpages?el={email_encoded}]]></url>
</emailClick>
</ad>
Email Clicks: XML
<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>
<ad>
<emailClick>
<url><![CDATA[https://mysite.com/landingpages?el={email_encoded}]]></url>
</emailClick>
</ad>
In-Stream Video, Outstream Video, Video Slider: XML
Note: See VAST Tag related documentation.
<?xml version="1.0" encoding="UTF-8"?>
<VAST version="3.0">
<Ad id="4440141">
<InLine>
<AdSystem>mysite.com</AdSystem>
<AdTitle/>
<Impression id="exotr">
<![CDATA[http://syndication.mysite.com/vregister.php?a=vimp&tracking_event=impression&idzone=4286963&2027add921916df3805db53a7c6af183=tsVuZ8uHLjt4ddvLjq4d_XDz65dddlTlK8E.etqayWunDNRRTXA3GxK9Yw85nw11QVuLvzVVysSOZyzSsSObmppNcDbDdrlNcFTlOfDXA3PYzHBU.5Tnw1wN1QVuZ8NcDeM0rmfDXA20xW49NThnw1wNtMSTsQPS58NcDdrFMDFcE0ufDXA3NVnw1wNs0zXVOU58NcDbblsDTmfDXA20xTTA5Tnw1wNwVT58NdVjOfDXaxHY5nw1z2MxwVPuUr0sVuZ8Nc9jMcFT7lK7VlNLkrWGaJ4GtpiSdiB6VdqymlyVrDNE8DW5e0.xK84vXMvPYzHBU.5Tnx1uXtPsSvOL1zLyuV3TUxZ8dbDa9eE7mfDW7NTIxXnrgblcrumpiz462prJa6cF5qYHoJWI81FFNb9dc6967s1NzFLbja7s1OeuBuemZuxqtdpitx6anDPhrnpgagleXkmbcjz4a36656s.GupqlxyVelyqaOyuCaXPXZU5SvA3nw12UxrvsVP564JJ6XKqoJpV6q2K7Ks.GuCSelyqqCaVeCW1iOBtelxiqaXPhrpcdcpcpXqgrcXfmqrlYkcz1sNsxzNRZ8NcDczrrlOfDXA3GxK3BK8vOw85nw1uXuNWVwTSr1wSOZ64G22K2GnJa3Kc.GuBtpimmByleqaylpzPhrlmqapgnrz4a4JWpnpYK5l5Jm3M.GutyqteSZtzPhrpcegmlXecmlYkcXgbz4a56Zr8F6q2K7Ks9vHXA3OxTXK5Tnw1tQV4LvOTSsSOLwN58NcrlbDVkFeC89M1.C9eE7meuVythqyCvBeema_BdtypqmCeuCaXPWw2zHM1Eva5TnrgknpcqqgmlXYjjXgltYjgbXpcYqmlqz4a6rGeWfDXVYzzz4a6mqYJ6168J3M9dTVME9a8rEjmeupqmCete1ynPWzTNdU5Sva5Tnw12058NcEtblMrEefDXZU5Su0xPPBK9nw12VOUrtMTzwSvLu0uUWOStYZ8NdtlkDefHty49fPXn269uXnl08c.vTtwY7.ejnXl5Y5cNdcEjlVbEk.fHty49fPXn2662ppooHGppanJa8.M]]>
</Impression>
<Error>
<![CDATA[http://syndication.mysite.com/vregister.php?a=vview&errorcode=[ERRORCODE]&idzone=4286963&dg=4440141-53781245-2-0-0-InLine]]>
</Error>
<Creatives>
<Creative sequence="1" id="53781245">
<Linear>
<Duration>00:00:14.40</Duration>
<TrackingEvents>
<Tracking id="prog_1" event="progress" offset="00:00:10.000">
<![CDATA[http://syndication.mysite.com/vregister.php?a=vview&tracking_event=progress&progress=00:00:10.000&idzone=4286963&2027add921916df3805db53a7c6af183=tsVuZ8uHLjt4ddvLjq4d_XDz65dddlTlK8E.etqayWunDNRRTXA3GxK9Yw85nw11QVuLvzVVysSOZyzSsSObmppNcDbDdrlNcFTlOfDXA3PYzHBU.5Tnw1wN1QVuZ8NcDeM0rmfDXA20xW49NThnw1wNtMSTsQPS58NcDdrFMDFcE0ufDXA3NVnw1wNs0zXVOU58NcDbblsDTmfDXA20xTTA5Tnw1wNwVT58NdVjOfDXaxHY5nw1z2MxwVPuUr0sVuZ8Nc9jMcFT7lK7VlNLkrWGaJ4GtpiSdiB6VdqymlyVrDNE8DW5e0.xK84vXMvPYzHBU.5Tnx1uXtPsSvOL1zLyuV3TUxZ8dbDa9eE7mfDW7NTIxXnrgblcrumpiz462prJa6cF5qYHoJWI81FFNb9dc6967s1NzFLbja7s1OeuBuemZuxqtdpitx6anDPhrnpgagleXkmbcjz4a36656s.GupqlxyVelyqaOyuCaXPXZU5SvA3nw12UxrvsVP564JJ6XKqoJpV6q2K7Ks.GuCSelyqqCaVeCW1iOBtelxiqaXPhrpcdcpcpXqgrcXfmqrlYkcz1sNsxzNRZ8NcDczrrlOfDXA3GxK3BK8vOw85nw12wNuTLuWuS1563KaZqWpm3M9cDbbFbDTktblOfDXA20xTTA5SvVNZS05nw1yzVNUwT158NcErUz0sFcy8kzbmfDXW5VWvJM25nw10uPQTSrvOTSsSOLwN58Nc9M1.C9VbFdlWe3jrgbnYprlcpz4a2oK8F3nJpWJHF4G8.GuVythqyCvBeema_BevCdzPXK5Ww1ZBXgvPTNfgu25U1TBPXBNLnrYbZjmaiXtcpz1wST0uVVQTSrsRxrwS2sRwNr0uMVTS1Z8NdVjPLPhrqsZ558NdTVME9a9eE7meupqmCeteViRzPXU1TBPWva5TnrZpmuqcpXtcpz4a7ac.GuCWtymViPPhrtssgbz49uXHr568.3Xt568effp579uDHfz0c68vHft111wSOVVsST58e3Lj189efbrrammigcamlqclrz4w]]>
</Tracking>
</TrackingEvents>
<VideoClicks>
<ClickThrough>
<![CDATA[https://syndication.mysite.com/click.php?data=H4sIAAAAAAAAA0VPOWrEQBD8ipJNhz7nCJ04ceA3jEcaVljHosNg04_3rByY6oKGKqq6RQRQ0NDux_HYb_xyo9c2X3lz_bAf45KPcV3cuU2urLMZEjW3J9Sk7NV.hm195O3zUhGckAOHphwikqgJRZ88myKatSIyVIMGe5aaBk1UmbnGFNmBsMbQ4imSoIJ_er1qLNLXD04ackqiUXzhUhgRayktB2wfj6Ff5zwu1yVwoZvG2p74nobufs7ruXV2mf9hjQx27fonSeP7m8WUGfoiFWqh7OsQasA4RCYMgDH9Aqi26WQ6AQAA]]>
</ClickThrough>
</VideoClicks>
<MediaFiles>
<MediaFile delivery="progressive" type="video/mp4">
<![CDATA[https://staticcdn.mysite.com/library/195600/5b7d9ad16e4b86ba8695f867e9a8464fc4444943.mp4]]>
</MediaFile>
</MediaFiles>
<Icons>
<Icon>
<IconClicks>
<IconClickThrough>var.destination.url.com</IconClickThrough>
</IconClicks>
</Icon>
</Icons>
</Linear>
</Creative>
</Creatives>
<Extensions>
<Extension>
<TitleCTA>
<MobileText>View More</MobileText>
<PCText>View More</PCText>
<DisplayUrl><![CDATA[]]></DisplayUrl>
<Tracking><![CDATA[https://click.tracking.com/click.php?data=H4sIAAAAAAAAA0...-]]></Tracking>
</TitleCTA>
</Extension>
</Extensions>
</InLine>
</Ad>
</VAST>
Popunder: XML
<?xml version="1.0" encoding="ISO-8859-1"?>
<ad>
<popunderAd>
<url><![CDATA[http://mysite.com/landingpages/mypage]]></url>
</popunderAd>
</ad>
Native Ads: JSON
For native ads the adm parameter should contain a JSON encoded string like this:
{
"native": {
"link": { "url": "https://mysite.com/landingpages/mypage" },
"eventtrackers": [
{
"event": 1,
"method": 1,
"url": "https://myEventTracker1.com"
}
],
"assets": [
{ "id": 1, "title": { "text": "Ad Title" } },
{ "id": 2, "data": { "value": "Ad description" } },
{
"id": 3,
"img": {
"url": "https://mysite.com/images/myad.jpg",
"w": 300,
“h”: 300,
}
}
]
}
}
Push Notification Ads: JSON
For Push Notification ads the adm parameter will contain a JSON encoded string like the following (note that we use the 'native' object to implement push notification ads). Width and height depend on the width and height coming from request. Currently supported dimensions are 192x192 and 720x480. One image asset per notification.
{\"native\":{\"link\":{\"url\":\"http:\/\/mysite.com\/landingpages\/mypage\"},\"assets\":[{\"id\":1,\"required\":1,\"img\":{\"url\":\"http:\/\/mysite.com\/images\/myad.jpg\",\"w\":720,\"h\":480}},{\"id\":2,\"title\":{\"text\":\"Ad Title\"}},{\"id\":3,\"data\":{\"type\":2,\"value\":\"Ad description\"}}]}}
Which is based on the following JSON object:
{
"native": {
"link": {
"url": "http://mysite.com/landingpages/mypage"
},
"assets": [
{
"id": 1,
"required": 1,
"img": {
"url": "http://mysite.com/images/myad.jpg",
"w": 720,
"h": 480
}
},
{
"id": 2,
"title": {
"text": "Ad Title"
}
},
{
"id": 3,
"data": {
"type": 2,
"value": "Ad description"
}
}
]
}
}
In-Page Push Notifications: JSON
{
"id": "d4b5c697-41f3-4c1c-a3d5-5fd01b5ef2aa",
"seatbid": [
{
"bid": [
{
"id": "6c821461440c755b8a1c4f3efdbd7549c5513895",
"impid": "90180978",
"price": 0.0035000000000000005,
"adm": "{\"native\":{\"link\":{\"url\":\"http:\/\/mysite.com\/landingpages\/mypage\"},\"assets\":[{\"id\":1,\"required\":1,\"img\":{\"url\":\"http:\/\/mysite.com\/images\/myad.jpg\",\"w\":720,\"h\":480}},{\"id\":2,\"title\":{\"text\":\"Ad Title\"}},{\"id\":3,\"data\":{\"type\":2,\"value\":\"Ad description\"}}]}}",
"ext": {
"btype": 1
},
"nurl": "http://network-domain.com/win-notification",
"cid": "4607067",
"crid": "60958939"
}
]
}
]
}
No Bid Response
To answer a bid request without making an actual bid, an HTTP response code 204 "No Content" will be sent.
Win Notification
When the parameter Bid Response Object -> Seat Bid Object -> Bid Object -> nurl is in the bid response, a GET request must be performed to such URL.