Connect bidder to Equativ SSP: bid request and bid response examples
Overview
This guide is for Equativ’s demand partners and explains how to use the OpenRTB API, including setup, configuration as well as the supported objects and parameters. This article contains bid request and bid response examples.
Examples
Example 1 - Simple Banner
Bid Request
{
"id": "337588032525303820",
"imp": [
{
"id": "933ef5a8-8a47-4f24-aad9-82c72dabf5dd",
"banner": {
"w": 300,
"h": 250,
"mimes": [
"text/html"
]
},
"tagid": "MSAx",
"bidfloor": 0.4460414,
"bidfloorcur": "EUR"
}
],
"site": {
"id": "234563",
"cat": [
"IAB2-1",
"IAB2-2"
],
"name": "name of my site",
"domain": "siteabcd.com",
"page": "http://siteabcd.com/page.htm"
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US; rv:1.9.2.16) Gecko/20110319 Firefox/3.6.16",
"ip": "64.124.253.1",
"geo": {
"country": "FRA",
"zip": "75001",
"type": 2
}
},
"user": {
"id": "5218014510113063703",
"buyeruid": "5df678asd8987656asdf78987654"
},
"at": 2,
"cur": [
"EUR"
],
"bcat": [
"1",
"82"
]
}Bid Response
{
"id":"1234534625254",
"seatbid":[
{
"bid":[
{
"id":"1",
"impid":"933ef5a8-8a47-4f24-aad9-82c72dabf5dd",
"price":9.43,
"adid":"314",
"cid":"campaign111",
"crid":"creative112",
"iurl":"http://adserver.com/pathtosampleimage.jpg",
"adomain":[
"advertiserdomain.com"
],
"nurl":"http://exampleadserver.com/winnoticeurl",
"adm":"%3C!DOCTYPE%20html%20PUBLIC%20%5C%22- %2F%2FW3C%2F%2FDTD%20XHTML%201.0%20Transitional%2F%2FEN%5C%22%20%5C%22htt p%3A%2F%2Fwww.w3.org%2FTR%2Fxhtml1%2FDTD%2Fxhtml1- transitional.dtd%5C%22%3E%3Chtml%20xmlns%3D%5C%22http%3A%2F%2Fwww.w3.org%2F1 999%2Fxhtml%5C%22%20xml%3Alang%3D%5C%22en%5C%22%20lang%3D%5C%22en%5C%22 %3E...%3C%2Fhtml%3E",
}
],
}
],
"cur":"EUR"
}Example 2 - Mobile
Bid Request
{
"id": "337588032537493520",
"imp": [
{
"id": "72b196e5-f115-4920-8828-d1a27f56615a",
"banner": {
"w": 300,
"h": 250,
"mimes": [
"text/html"
]
},
"tagid": "MSAx"
}
],
"app": {
"id": "123123",
"name": "name of my app",
"bundle": "com.appname.my",
"cat": [
"IAB2-1",
"IAB2-2"
],
"domain": "appdomain.com"
},
"device": {
"ua": "Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_2_1 like Mac OS X; en-us) AppleWebKit/532.9 (KHTML, like Gecko) Version/4.0.5 Mobile/8A306 Safari/6531.22.7",
"ip": "64.124.253.1",
"geo": {
"country": "FRA",
"zip": "75001",
"type": 2,
"lat": 45.7446632,
"lon": 4.84789
},
"dpidsha1": "0d0f2b7c5ec66a8f13770e4521c5390597402cd2",
"dpidmd5": "d5d80d994ff58090d7efe720d4a43242",
"make": "Apple",
"model": "iPhone",
"os": "iOS",
"osv": "7_1_2",
"connectiontype": 2,
"devicetype": 4,
"language": "fr",
"ifa": "7f487efd02b5691a"
},
"user": {
"id": "2159307320102338611",
"buyeruid": "5df678asd8987656asdf78987654"
},
"at": 2,
"cur": [
"EUR"
],
"bcat": [
"1",
"82"
]
}Bid Response
{
"id":"1234534625254",
"seatbid":[
{
"bid":[
{
"id":"1",
"impid":"72b196e5-f115-4920-8828-d1a27f56615a",
"price":9.43,
"adid":"314",
"cid":"campaign111",
"crid":"creative112",
"iurl":"http://adserver.com/pathtosampleimage.jpg",
"adomain":[
"advertiserdomain.com"
],
"nurl":"http://exampleadserver.com/winnoticeurl",
"adm":"%3C!DOCTYPE%20html%20PUBLIC%20%5C%22- %2F%2FW3C%2F%2FDTD%20XHTML%201.0%20Transitional%2F%2FEN%5C%22%20%5C%22htt p%3A%2F%2Fwww.w3.org%2FTR%2Fxhtml1%2FDTD%2Fxhtml1- transitional.dtd%5C%22%3E%3Chtml%20xmlns%3D%5C%22http%3A%2F%2Fwww.w3.org%2F1 999%2Fxhtml%5C%22%20xml%3Alang%3D%5C%22en%5C%22%20lang%3D%5C%22en%5C%22 %3E...%3C%2Fhtml%3E",
}
],
}
],
"cur":"EUR"
}Example 3 - Private marketplace
Bid Request
{
"id": "337588032573472826",
"imp": [
{
"id": "4f332042-55af-4433-803b-bb43a5b5d2a0",
"banner": {
"w": 300,
"h": 250,
"mimes": [
"text/html"
]
},
"tagid": "MSAx",
"bidfloor": 0.03,
"bidfloorcur": "EUR",
"pmp": {
"private_auction": 1,
"deals": [
{
"id": "AB-Agency1-0001",
"bidfloor": 2.5,
"bidfloorcur": "EUR",
"wseat": [
"Agency1"
],
"at": 2
},
{
"id": "XY-Agency2-0001",
"bidfloor": 2.0,
"bidfloorcur": "EUR",
"wseat": [
"Agency2"
],
"at": 2
}
]
}
}
],
"site": {
"id": "102855",
"cat": [
"IAB3-1"
],
"domain": "www.foobar.com",
"page": "http://www.foobar.com/1234.html"
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US; rv:1.9.2.16) Gecko/20110319 Firefox/3.6.16",
"ip": "64.124.253.1",
"geo": {
"country": "FRA",
"zip": "75001",
"type": 2
}
},
"user": {
"id": "5218014510113063703"
},
"at": 2,
"cur": [
"EUR"
]
}Bid response
{
"bidid":"abc1123",
"cur":"USD",
"id":"80ce30c53c16e6ede735f123ef6e32361bfc7b22",
"seatbid":[
{
"bid":[
{
"adid":"314",
"adm":"%3C!DOCTYPE%20html%20PUBLIC%20%5C%22-‐%2F%2FW3C%2F%2FDTD%20XHTML%201.0%20Transitional%2F%2FEN%5C%22%20%5C%22http%3A%2F%2Fwww.w3.org%2FTR%2Fxhtml1%2FDTD%2Fxhtml1-‐transitional.dtd%5C%22%3E%3Chtml%20xmlns%3D%5C%22http%3A%2F%2Fwww.w3.org%2F1999%2Fxhtml%5C%22%20xml%3Alang%3D%5C%22en%5C%22%20lang%3D%5C%22en%5C%22%3E...%3C%2Fhtml%3E",
"adomain":[
"advertiserdomain.com"
],
"attr":[
1,
2,
3,
4
],
"dealid":"AB-‐Agency1-‐0001",
"id":"1",
"impid":"4f332042-55af-4433-803b-bb43a5b5d2a0",
"adid":"314",
"cid":"campaign111",
"crid":"creative112",
"iurl":"http://exampleadserver.com/pathtosampleimage.jpg",
"nurl":"http://exampleadserver.com/winnoticeurl",
"price":5.0
}
],
"seat":"Agency1"
}
]
}Example 4 - Video
On our end, we’re able to make a specific targeting between instream and outstream. From OpenRTB 2.5 this is clearly indicated by the video.placement field which will be transmitted. Plus, we make the difference between Preroll, Midroll and Postroll with startdelay data. Below are the bid requests:
Instream Bid Request (Web)
{
"id": "337588032613056577",
"imp": [
{
"id": "c56693bd-f9b0-40c1-bf53-62551c4676ff",
"video": {
"mimes": [
"video/mp4",
"video/x-flv",
"application/javascript",
"application/x-shockwave-flash"
],
"linearity": 1,
"minduration": 1,
"maxduration": 60,
"protocols": [
2,
3,
5,
6
],
"w": 640,
"h": 480,
"startdelay": 0,
"battr": [
9,
10,
14
],
"api": [
1,
2
],
"playbackmethod": [
3
],
"boxingallowed": 1
},
"tagid": "MSAx",
"bidfloor": 0.01,
"bidfloorcur": "EUR"
}
],
"site": {
"id": "234563",
"cat": [
"IAB2-1",
"IAB2-2"
],
"name": "Smart RTB+ Monitoring",
"domain": "rtbmonitoring.smartadserver.com",
"page": "http://rtbmonitoring.smartadserver.com/page.htm",
"publisher": {
"id": "893",
"name": "Smart RTB+"
}
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
"ip": "10.203.0.17",
"geo": {
"country": "FRA"
},
"devicetype": 2
},
"user": {
"id": "5218014510113063703"
},
"at": 2,
"cur": [
"EUR"
]
}Instream Bid Request (Mobile Web)
For the Mobile Web, we send a web bid request adding the following in device object : OS, Connectiontype, Devicetype
Instream Bid Request (Mobile App)
{
"id": "337588032633176135",
"imp": [
{
"id": "1f5d11e2-bf0d-4bd8-9073-29370e2dddbd",
"video": {
"mimes": [
"video/mp4",
"video/x-flv",
"application/javascript",
"application/x-shockwave-flash"
],
"linearity": 1,
"minduration": 1,
"maxduration": 60,
"protocols": [
2,
3,
5,
6
],
"w": 640,
"h": 480,
"startdelay": 0,
"battr": [
9,
10,
14
],
"api": [
1,
2
],
"playbackmethod": [
3
],
"boxingallowed": 1
},
"tagid": "MSAx",
"bidfloor": 0.01,
"bidfloorcur": "EUR"
}
],
"app": {
"id": "234563",
"name": "Smart RTB+ Monitoring",
"bundle": "com.smartadserver.monitoring",
"cat": [
"IAB2-1",
"IAB2-2"
],
"domain": "rtbmonitoring.smartadserver.com",
"publisher": {
"id": "893",
"name": "Smart RTB+"
}
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
"ip": "10.203.0.17",
"geo": {
"country": "FRA"
},
"os": "Unknown",
"connectiontype": 3,
"devicetype": 4
},
"user": {
"id": "5218014510113063703"
},
"at": 2,
"cur": [
"EUR"
]
}Outstream Bid Request (Web, Mobile Web, Mobile App)
In order to facilitate out-stream specific targeting (particularly before the advent of the OpenRTB 2.5 video.placement field), we transmit a flag in the extension of video impression requests. When the flag smart_context is present and equal to 1, the impression is out-stream. In any other case the impression is in-stream video.
Example of the extension for out-stream:
"video": {
"ext": {
"smart_context": 1
}
}Bid response - case 1: VAST URL returned
{
"id":"1234567890",
"seatbid":[
{
"bid":[
{
"id":"kljaf9",
"impid":"9ced38d5-089b-4c0e-9f72-3d94a2abafc9",
"price":9.43,
"nurl":"http://exampleadserver.com/WinNoticeUrlThatReturnsVAST",
"adid":"314",
"cid":"campaign111",
"crid":"creative112",
"iurl":"http://adserver.com/pathtosampleimage.jpg"
}
]
}
]
}Bid response - case 2 : VAST XML Document Returned Inline
{
"id":"123",
"seatbid":[
{
"bid":[
{
"id":12345,
"impid":"9ced38d5-089b-4c0e-9f72-3d94a2abafc9" ,
"price":3.00,
"nurl":"http://exampleadserver.com/winnoticeurl",
"adomain":[
"advertiserdomain.com"
],
"adid":"314",
"cid":"campaign111",
"crid":"creative112",
"iurl":"http://adserver.com/pathtosampleimage.jpg",
"adm":"%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22utf - 8%22%3F%3E%0A%3CVAST%20version%3D%222.0%22%3E%0A%20%20%20%20%3CAd%2 0id% 3D%2212345%22%3E%0A%20%20%20%20%20%20%20%20%3CInLine%3E%0A%20%20%20%20 %20%20%20%20%20%20%20%20%3CAdSystem%20version%3D%221.0%22%3ESpotXchange%3 C%2FAdSystem%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3C AdTitle%3E%3C!%5BCDATA%5BSample%20VAST%5 D%5D%3E%3C%2FAdTitle%3E%0A%20%20%20 %20%20%20%20%20%20%20%20%20%20%20%20%20%3CImpression%3Ehttp%3A%2F%2Fsa mple.com%3C%2FImpression%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20 %20%20%3CDescription%3E%3C!%5BCDATA%5BA%20sample%20VAST%20feed%5D%5D%3E% 3C%2FDe scription%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20% 3CCreatives%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20 %20%20%3CCreative%20sequence%3D%221%22%20id%3D%221%22%3E%0A%20%20%20%20 %20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20% 0%20%20%20%3CLinear %3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%2 0%20%20%20%20%20%20%20%3CDuration%3E00%3A00%3A30%3C%2FDuration%3E%0A%20 %20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20 %20%20%20%20%3CTrackingEvents %3E%0A%20%20%20%20%20%20%20%20%20%20%20%20 %20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3C%2FTrackingEvents%3 E%20%20%20%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20 %20%20%20%20%20%20%20%20%20%20%3CVideoClicks%3E%0A%20%20%20%20%20%20%20 %20%20 %20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%2 0%20%20%3CClickThrough%3E%3C!%5BCDATA%5Bhttp%3A%2F%2Fsample.com%2Fopenrtbtes t%5D%5D%3E%3C%2FClickThrough%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20 %20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20 %3C%2FVideoClicks%3E%0A %20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%2 0%20%20%20%20%20%3CMediaFiles%3E%0A%20%20%20%20%20%20%20%20%20%20%20%2 0%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3CMedi aFile%20delivery%3D%22progr essive%22%20bitrate%3D%22256%22%20width%3D%22640%22 %20height%3D%22480%22%20type%3D%22video%2Fmp4%22%3E%3C!%5BCDATA%5Bhttp%3 A%2F%2Fsample.com%2Fvideo.mp4%5D%5D%3E%3C%2FMediaFile%3E%0A%20%20%20%20% 20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%2 0%20%20 %20%3C%2FMediaFiles%3E%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20 OPENRTB API Specification Version 2.2 RTB Project Page 62 %20%20%20%20%20%20%20%20%20%3C%2FLinear%3E%0A%20%20%20%20%20%20%20%20 %20%20%20%20%20%20%20%20%20%20%20%20%3C%2FCreative%3E%0A%20%20%20%20%2 0%20%20%20%20%20%20%20%20%20%20%20%3C%2F Creatives%3E%0A%20%20%20%20%20 %20%20%20%3C%2FInLine%3E%0A%20%20%20%20%3C%2FAd%3E%0A%3C%2FVAST%3E" }
]
}
]
}Example 5 - Native
Bid Request (Mobile Web, native 1.0)
{
"id": "337588032640122954",
"imp": [
{
"id": "aa4347e5-d04c-4aed-b2ea-29cf01b589e4",
"native": {
"request": "{\"native\":{\"ver\":\"1\",\"layout\":3,\"adunit\":2,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":40}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"w\":160,\"wmin\":150,\"h\":120,\"hmin\":110}},{\"id\":3,\"required\":1,\"data\":{\"type\":1,\"len\":200}}]}}",
"ver": "1"
},
"tagid": "MSAx",
"bidfloor": 0.01,
"bidfloorcur": "EUR"
}
],
"site": {
"id": "12345",
"cat": [
"IAB2-1",
"IAB2-2"
],
"name": "Foobar",
"domain": "www.foobar.com",
"page": "http://www.foobar.com/page.htm",
"publisher": {
"id": "123",
"name": "Smart RTB+"
}
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
"ip": "10.203.2.121",
"geo": {
"country": "FRA"
},
"os": "Unknown",
"connectiontype": 3,
"devicetype": 4
},
"user": {
"id": "5218014510113063703"
},
"at": 2,
"cur": [
"EUR"
]
}Bid request (Mobile Web, native 1.2)
{
"id": "337588032640122954",
"imp": [{
"id": "aa4347e5-d04c-4aed-b2ea-29cf01b589e4",
"native": {
"request": "{\"native\":{\"ver\":\"1.2\",\"plcmttype\":1,\"context\":11,\"privacy\":1,\"eventrackers\":[{\"event\":1,\"methods\":[1,2]}],\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":40}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"w\":160,\"wmin\":150,\"h\":120,\"hmin\":110}},{\"id\":3,\"required\":1,\"data\":{\"type\":1,\"len\":200}}]}}",
"ver": "1",
"api": []
},
"tagid": "MSAx",
"bidfloor": 0.01,
"bidfloorcur": "EUR"
}
],
"site": {
"id": "12345",
"cat": [
"IAB2-1",
"IAB2-2"
],
"name": "Foobar",
"domain": "www.foobar.com",
"page": "http://www.foobar.com/page.htm",
"publisher": {
"id": "123",
"name": "Smart RTB+"
}
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
"ip": "10.203.2.121",
"geo": {
"country": "FRA"
},
"os": "Unknown",
"connectiontype": 3,
"devicetype": 4
},
"user": {
"id": "5218014510113063703"
},
"at": 2,
"cur": [
"EUR"
]
}Bid request (App, native 1.0)
{
"id": "337588032645038156",
"imp": [
{
"id": "01ef1ee4-b322-4e09-8341-081dff5a7723",
"native": {
"request": "{\"native\":{\"ver\":\"1\",\"layout\":3,\"adunit\":2,\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":40}},{\"id\":2,\"required\":1,\"img\":{\"type\":3,\"w\":160,\"wmin\":150,\"h\":120,\"hmin\":110}},{\"id\":3,\"required\":1,\"data\":{\"type\":1,\"len\":200}}]}}",
"ver": "1"
},
"tagid": "MSAx",
"bidfloor": 0.01,
"bidfloorcur": "EUR"
}
],
"app": {
"id": "234563",
"name": "Smart RTB+ Monitoring",
"bundle": "com.smartadserver.monitoring",
"cat": [
"IAB2-1",
"IAB2-2"
],
"domain": "rtbmonitoring.smartadserver.com",
"publisher": {
"id": "893",
"name": "Smart RTB+"
}
},
"device": {
"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
"ip": "10.203.2.121",
"geo": {
"country": "FRA"
},
"os": "Unknown",
"connectiontype": 3,
"devicetype": 4
},
"user": {
"id": "5218014510113063703"
},
"at": 2,
"cur": [
"EUR"
]
}Bid response (Mobile Web, native 1.0)
{
"id": "123",
"seatbid": [{
"bid": [{
"id": "12345",
"impid": "2",
"price": 3.00,
"nurl": "http://example.com/winnoticeurl",
"adm": "{\"native\":{\"ver\":1,\"link\":{ ... },\
"imptrackers\":[ ... ],\"assets\":[ ... ]}}"
}]
}]
}