Demand Partners (DSPs) Tech Specification

Contents

1.1. Bid Request Parameters

1.2. Bid Request Example

2.1. Bid Response Parameters

2.2. Bid Response Example

Requests to DSPs are sent via JSON using OpenRTB 2.5 protocol. We use nurl to notify a DSP about bid win.

1.1. Bid Request Parameters

1.1.1 Object: BidRequest

Attribute Type Description
id string; required Unique ID of the bid request, provided by the exchange.
imp object array; 
required 
Array of Imp objects representing the impressions offered. At least 1 Imp object is required. 
site object; 
recommended 
Details via a Site object about the publisher’s website. Only applicable and recommended for websites. 
app object; recommended  Details via an App object about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps.
device object; 
recommended 
Details via a Device object about the user’s device to which the impression will be delivered. 
user object; 
recommended 
Details via a User object about the human user of the device; the advertising audience. 
at integer; 
default 2 
Auction type, where 1 = First Price, 2 = Second Price Plus. Exchange-specific auction types can be defined using values greater than 500.  
tmax integer  Maximum time in milliseconds the exchange allows for bids to be received including Internet latency to avoid timeout. This value supersedes any a priori guidance from the exchange. 
cur string array Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies. 
1.1.2 Object: Imp
Attribute Type Description
id string; required A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments). 
banner object A Banner object; required if this impression is offered as a banner ad opportunity. 
video object  A Video object; required if this impression is offered as a video ad opportunity.
native object  A Native object; required if this impression is offered as a native ad opportunity. 
instl integer; 
default 0 
1 = the ad is interstitial or full screen, 0 = not interstitial.
tagid string Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging of any issues, or for optimization by the buyer. 
bidfloor float; default 0  Minimum bid for this impression expressed in CPM.
secure integer 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. 
1.1.3 Object: Banner
Attribute Type Description
w integer  Exact width in device independent pixels (DIPS); 
recommended if no format objects are specified. 
h integer  Exact height in device independent pixels (DIPS); 
recommended if no format objects are specified. 
battr integer array Blocked creative attributes. 
1.1.4 Object: Video
Attribute Type Description
mimes  string array; required  Content MIME types supported (e.g., “video/x-ms-wmv”, “video/mp4”).
minduration integer; recommended Minimum video ad duration in seconds.
maxduration integer; recommended  Maximum video ad duration in seconds.
protocols  integer array; recommended  Array of supported video protocols. At least one supported protocol must be specified in either the protocol or protocols attribute. 
w integer; recommended Width of the video player in device independent pixels (DIPS).
h integer; recommended Height of the video player in device independent pixels (DIPS).
1.1.5 Object: Native
Attribute Type Description
request  string; required Request payload complying with the Native Ad Specification.
ver string; recommended Version of the Dynamic Native Ads API to which request complies; highly recommended for efficient parsing.
battr  integer array  Blocked creative attributes.
1.1.6 Object: Site
Attribute Type Description
id string; 
recommended 
Exchange-specific site ID. 
name string Site name (may be aliased at the publisher’s request).
domain string Domain of the site (e.g., “mysite.foo.com”).
cat string array  Array of IAB content categories of the site. 
pagecat string array  Array of IAB content categories that describe the current page 
or view of the site.  
page string URL of the page where the impression will be shown.
publisher object  Details about the Publisher of the site.
1.1.7 Object: App
Attribute Type Description
id string; recommended  Exchange-specific app ID. 
name string App name (may be aliased at the publisher’s request). 
bundle string A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is typically a numeric ID. 
storeurl string    App store URL for an installed app; for IQG 2.1 compliance.
1.1.8 Object: Publisher
Attribute Type Description
id string Exchange-specific publisher ID.
1.1.9 Object: Device
Attribute Type Description
ua string; 
recommended 
Browser user agent string.
geo object; 
recommended 
Location of the device assumed to be the user’s current 
location defined by a Geo object. 
dnt integer; 
recommended 
Standard “Do Not Track” flag as set in the header by the 
browser, where 0 = tracking is unrestricted, 1 = do not track. 
ip string; 
recommended 
IPv4 address closest to device.
devicetype integer The general type of device. 
make string Device make (e.g., “Apple”).
model string Device model (e.g., “iPhone”).
os string Device operating system (e.g., “iOS”). 
osv string Device operating system version (e.g., “3.1.2”).
js integer  Support for JavaScript, where 0 = no, 1 = yes.
language string Browser language using ISO-639-1-alpha-2.
carrier string Carrier or ISP (e.g., “VERIZON”) using exchange curated string 
names which should be published to bidders a priori. 
connectiontype integer Network connection type. 
1.1.10 Object: GEO
Attribute Type Description
type integer  Source of location data; recommended when passing 
lat/lon. Refer to List 5.20. 
country string Country code using ISO-3166-1-alpha-3. 
region string Region code using ISO-3166-2; 2-letter state code if USA. 
metro string  Google metro code; similar to but not exactly Nielsen DMAs. 
See Appendix A for a link to the codes. 
city string City using United Nations Code for Trade & Transport 
Locations. See Appendix A for a link to the codes. 
zip string Zip or postal code.
1.1.11 Object: User
Attribute Type Description
id string; 
recommended 
Exchange-specific ID for the user. At least one of id or 
buyeruid is recommended. 

1.2. Bid Request Example

{   "id": "1-e3241aed85d6ed4-482","imp": [       {

           "id": "3972",

           "banner": {

               "w": 320,

               "h": 50,

               "battr": [

                   1,

                   6,

                   8,

                   10,

                   14

               ]

           },

           "instl": 0,

           "tagid": "1087575",

           "bidfloor": 0.6883333333333334,

           "secure": 0

       }

   ],

   "site": {

       "id": "7662efc4ea7c",

       "name": "todays-headlines.mobileposse.com",

       "domain": "todays-headlines.mobileposse.com",

       "cat": [

           "IAB12"

       ],

       "pagecat": [

           "IAB12"

       ],

       "page": "http://todays-headlines.mobileposse.com/section/us?sch=pm&alias=nightnews&utm_medium=notification&mpnav=start",

       "publisher": {

           "id": "156078"

       }

   },

   "device": {

       "ua": "Mozilla/5.0 (Linux; Android 5.1.1; LGMS345 Build/LMY47V; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/46.0.2490.76 Mobile Safari/537.36",

       "geo": {

           "type": 2,

           "country": "USA",

           "region": "pa",

           "metro": "504",

           "city": "philadelphia",

           "zip": "19130"

       },

       "dnt": 0,

       "ip": "208.54.90.178",

       "devicetype": 1,

       "make": "LG",

       "model": "MS345",

       "os": "android",

       "osv": "5.1.1",

       "js": 1,

       "language": "en",

       "carrier": "T-Mobile USA",

       "connectiontype": 3

   },

   "user": {

       "id": "100:user.id:b2da0a89b08e038451d7aeec93e19d263cfae274"

   },

   "at": 2,

   "tmax": 80,

   "cur": [

       "USD"

   ]

}

2.1. Bid Response Parameters

2.1.1 Object: BidResponse

Attribute Type Description
id string; required ID of the bid request to which this is a response. 
bidid string Bidder generated response ID to assist with logging/tracking.
seatbid object array Array of seatbid objects; 1+ required if a bid is to be made.
cur string; 
default “USD” 
Bid currency using ISO-4217 alpha codes. 
2.1.2 Object: SeatBid
Attribute Type Description
bid object array; 
required 
Array of 1+ Bid objects each related to an 
impression. Multiple bids can relate to the same impression. 
seat string ID of the buyer seat (e.g., advertiser, agency) on whose behalf 
this bid is made. 
2.1.3 Object: Bid
Attribute Type Description
id string; required Bidder generated bid ID to assist with logging/tracking.
adid string ID of a preloaded ad to be served if the bid wins.
nurl string Win notice URL called by the exchange if the bid wins (not 
necessarily indicative of a delivered, viewed, or billable ad); 
optional means of serving ad markup. Substitution macros 
may be included in both the URL and optionally 
returned markup. 
price float; required Bid price expressed as CPM although the actual transaction is 
for a unit impression only. Note that while the type indicates 
float, integer math is highly recommended when handling 
currencies (e.g., BigDecimal in Java). 
impid string; required  ID of the Imp object in the related bid request.
crid string; required Creative ID to assist with ad quality checking. 
cid string Campaign ID to assist with ad quality checking; the collection 
of creatives for which iurl should be representative. 
adomain string array Advertiser domain for block list checking (e.g., “ford.com”). 
This can be an array of for the case of rotating creatives. 
Exchanges can mandate that only one domain is allowed. 
adm string Optional means of conveying ad markup in case the bid wins; 
supersedes the win notice if markup is included in both. 
Substitution macros may be included. 
iurl string URL without cache-busting to an image that is representative 
of the content of the campaign for ad quality/safety checking. 
cat string array IAB content categories of the creative.
ext object Placeholder for bidder-specific extensions to OpenRTB.
   

2.2. Bid Response Example

{

   "id": "1-e3241aed85d6ed4-482",

   "bidid": "9966aeb821cd91479eddb0e31bfdc064",

   "seatbid": [

       {

           "bid": [

               {

                   "id": "5a02f0d1108921510142161",

                   "adid": "sf023eea64-96c7-473e-8cbd-0df53",

                   "nurl": "https://track.example.com/win?aid=${AUCTION_ID}&ap=${AUCTION_PRICE}&bid_id=${AUCTION_BID_ID}&imp_id=${AUCTION_IMP_ID}&ad_id=${AUCTION_AD_ID}&cur=${AUCTION_CURRENCY}&s1=v1AAEFAAir9.PCyHlVcwACBAAEAAAAVAATBAAEAAAAVAADBAAEAAAANAAEBgAIP_XCj1wo9cMABQYACD_1wo9cKPXDABEGAAg_8n752yLQ5gAGBwAfZGMwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAHBwAfeXUwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAIBwAfc2YwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAJBwABMQALBwAAAAwEAAQAAAAAAA0GAAg_wzMzMzMzMwAONgAAAA82AAAAEDgAAAASBwADVVNE&s2=aHR0cDovL3RyYWZmaWMuMTgwNS50ZWNoL3VzZXJzbnljLnBocD9wcmljZT0ke0FVQ1RJT05fUFJJQ0V9JmJpZF9pZD0ke0FVQ1RJT05fQklEX0lEfSZyZXFpZD0ke0FVQ1RJT05fSUR9JnJuPWZiZTg3ODc5ZTFiN2Y3MWNlY2NjMTE2Y2NjOWI2NGEwJmlwPTIwOC41NC45MC4xNzgwZTNjNzAxYy1lNDY3LTQ4YzItYTZmMy00YzA0YWMyNDhiZjkmZnJlcT0xMiZ0b2tlbj03NjYyZWZjNGVhN2MlN0MlN0MlN0N0b2RheXMtaGVhZGxpbmVzLm1vYmlsZXBvc3NlLmNvbSU0MDBlM2M3MDFjLWU0NjctNDhjMi1hNmYzLTRjMDRhYzI0OGJmOSZzaXRlX2lkPTc2NjJlZmM0ZWE3YyZjcD15dTAyM2VlYTY0LTk2YzctNDczZS04Y2JkLTBkZjUz",

                   "price": 1.156,

                   "impid": "1",

                   "crid": "yu023eea64-96c7-473e-8cbd-0df53",

                   "cid": "dc023eea64-96c7-473e-8cbd-0df53",

                   "adomain": [

                       "viber.com"

                   ],

                   "adm": "<img src=\"http://track.us.example.com/imp?aid=${AUCTION_ID}&ap=${AUCTION_PRICE}&s1=v1AAEFAAir9.PCyHlVcwACBAAEAAAAVAATBAAEAAAAVAADBAAEAAAANAAEBgAIP_XCj1wo9cMABQYACD_1wo9cKPXDABEGAAg_8n752yLQ5gAGBwAfZGMwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAHBwAfeXUwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAIBwAfc2YwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAJBwABMQALBwAAAAwEAAQAAAAAAA0GAAg_wzMzMzMzMwAONgAAAA82AAAAEDgAAAASBwADVVNE\" width=\"0\" height=\"0\" style=\"display:none\"><script>var s_ad_pub = '156078' ,s_psid = '7662efc4ea7c' , s_bidvisi = 'ABF7E3C2C8795573' ,s_cli_ip = '208.54.90.178',s_cli_geo = 'USA' ,s_cli_spe = 'USA' ,s_cli_dev = '3' ,s_cli_os = 'android' ,s_cli_uuid = '0e3c701c-e467-48c2-a6f3-4c04ac248bf9' , s_pub_fingerprint = 'LiMTU2MTExNDIwMQ==', s_cli_dev_id = '12';</script><a href='https://play.google.com/store/apps/details?id=com.viber.voip'><img  src='https://s3.amazonaws.com/830d-4cd2-b585-2166481d/85-216.jpg' /></a>\r\n<script src=\"https://s3.amazonaws.com/830d-4cd2-b585-2166481d/35cae7.js\"></script>",

                   "iurl": "https://s3.amazonaws.com/smabfuihei/64a3ff2d7b4f3496beb0.png",

                   "cat": [

                       "IAB9"

                   ],

                   "ext": {

                       "imptrackers": []

                   }

               }

           ],

           "seat": "pio"

       }

   ],

   "cur": "USD"

}

Still need help? Contact Us Contact Us