OpenRTB Request

The Open RTB request for standard format is fully compliant with Open RTB 2.3 standards.

Bid Request Structure

- Sample Request
- Sample Response

AttributeTypeDescription
idstringUnique ID of the bid request, provided by the exchange.
impobjectUnique ID of the bid request, provided by the exchange.
siteobjectPN will send this for mobile websites.
appobjectPN will send this for apps only
deviceobjectDetails via a Device object about the user’s device to which the impression will be delivered.
userobjectDetails via a User object about the human user of the device; the advertising audience.
atintegerAuction type, where 1 = First Price, 2 = Second Price Plus.
PN conducts a second price auction.
tmaxintegerMaximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline.
wseatarrayWhitelist of buyer seats allowed to bid on this impression. Seat IDs must be communicated between bidders and the exchange a priori. Omission implies no seat restrictions.
allimpsinteger; default 0Flag to indicate if Exchange can verify that the impressions offered represent all of the impressions available in context (e.g., all on the web page, all video spots such as pre/mid/post roll) to support road-blocking. 0 = no or unknown, 1 = yes, the impressions offered represent all that are available.
curstring arrayArray of allowed currencies for bids on this bid request using ISO-4217 alpha codes. PN only allows bidding in USD
bcatstring arrayBlocked advertiser categories using the IAB content categories. DSP need to respect bcat to align with PN publishers and exchange wide settings
badvBlock list of advertisers by their domains (e.g., “ford.com”). Typically designated by publishers

Definition of the Impression Object

AttributeTypeDescription
idstring; requiredA unique identifier for this impression within the context of the bid request.
bannerobject; requiredA Banner object; Details below
bidfloorfloatMinimum bid for this impression expressed in CPM.
bidfloorcurstring; default “USD”Currency specified using ISO-4217 alpha codes. Pubnative only support USD

Definition of the Impression Ext Object

AttributeTypeDescription
hbintegerAn integer value describing if the auction is “waterfall” or not.
“1” = The auction is not waterfall
“0” = The auction is waterfall

Definition of the Banner Object

AttributeTypeDescription
winteger; requiredWidth of the impression in pixels.
If neither wmin nor wmax are specified, this value is an exact width measurement. Otherwise it is a preferred width.
hinteger; recommendedHeight of the impression in pixels.
If neither hmin nor hmax are specified, this value is an exact height measurement. Otherwise it is a preferred height
wmaxinteger; optionalMaximum width of the impression in pixels.
If included along with a w value, then w should be interpreted as a recommended or preferred width.
hmaxinteger; optionalMaximum height of the impression in pixels
If included along with a h value, then h should be interpreted as a recommended or preferred height.
wmininteger; optionalMinimum width of the impression in pixels.
hmininteger; optionalMinimum height of the impression in pixels.
idstring; optionalUnique identifier for the banner object.
Recommended when Banner objects are used with a Video object to represent an array of companion ads. Values usually start at 1 and increase with each object; should be unique within an impression.
btypeinteger array ; optionalBlocked banner ad types.
battrinteger array ; optionalBlocked creative attributes.
posinteger ; optionalAd position on screen.
mimesstring array ; optionalContent MIME types supported.
Popular MIME types may include “application/x-shockwave-flash”, “image/jpg”, and “image/gif”.
topframeinteger ; optionalIndicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.
expdirinteger array ; optionalDirections in which the banner may expand
apiinteger array ; optionalList of supported API frameworks for this impression
extobject ; optionalPlaceholder for exchange-specific extensions to OpenRTB
....
"banner": {
             "w": 728, "h": 90, "pos": 1,
             "btype": [ 4 ],
             "battr": [ 14 ],
             "api": [ 3 ]
}
....

Definition of the App Object

FieldScopeType
idstring;
recommended
Pubnative - specific app ID.
namestringPubnative - specific App name
bundlestringApplication bundle or package name (e.g., com.foo.mygame);
storeurlstringApp store URL for an installed app;
catstring arrayArray of IAB content categories of the app.
verstringApplication version
publisherobjectDetails about the Publisher
keywordsstringComma separated list of keywords about the app.
"app":{  
      "id":"1004844",
      "name":"Countabc",
      "bundle":"com.foo.mygame",
      "storeurl":"https://play.google.....", 
      "cat":[  
         "IAB18"
      ],
      "keywords":"shopping", 
      "ver":"10.1", 
      "publisher":{  
         "id":"1028",
         "name":"Count LTD",
      }
   },

Definition of the Device Object

FieldScopeType
uastring;
recommended
Browser user agent string.
geoobject;
recommended
Location of the device assumed to be the user’s current.
geo.type - Possible values 1,2
1- Geo info generated from GPS system
2- Geo info generated from IP address.
dntinteger;
recommended
Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track.
ipstring;
recommended
IPv4 address closest to device.
devicetypeintegerThe general type of device.
makestringDevice make (e.g., “Apple”).
modelstringDevice model (e.g., “iPhone”).
osstringDevice operating system (e.g., “iOS”).
osvstringDevice operating system version
hwvstringHardware version of the device
carrierstringCarrier or ISP (e.g., “VERIZON”). “WIFI” is often used in mobile to indicate high bandwidth (e.g., video friendly vs. cellular).
connectiontypeintegerNetwork connection type.
0 -Unknown, 1- Ethernet, 2 - WIFI, 3 -Cellular Network – Unknown Generation
devicetypeintegerThe general type of device
ifastringID sanctioned for advertiser use in the clear (i.e., not hashed)

Device Ext Object

AttributeTypeDescription
inputlanguagestringA string array containing the languages setup on the user's device keyboard. (i.e. “en-US, en” )
diskspaceintAn integer value describing the available disk space on the device in megabytes, where i.e. "18201" = device has 18201 MB of available disk space.
totaldiskintAn integer value describing the total disk space on the device in megabytes, where i.e. "63989" = 63989 MB of total disk space.
ringmuteint(Android only) An integer value describing the device sound setting during time of ad request describing if sound is set to ring or mute, where
"0" = mute and
"1" = ring.
chargingintAn integer value describing if the device is connected to a charger, where:
"0" = unplugged and
"1" = plugged into power outlet
headsetboolA boolean value indicating if the device is connected to a headset, where:
"1" = device is connected to any headset and
"0" = no headset is connected
batterylevelintAn integer passed describing percent battery remaining on the user's device, segmented into buckets, where
100-85% = 8
84-70% = 7
69-55% = 6
54-40% = 5
39-25% = 4
21-10% = 3
9-5% = 2
< 5% = 1
batterysaverboolA boolean value indicating if battery saver ("Low Power Mode" on iOS) has been enabled, where
"1" = battery saver,
"0" = not enabled
darkmodeboolA boolean value indicating if dark mode is enabled on the device, where
"1" = dark mode enabled,
"0"= not enabled
airplaneboolA boolean value indicating if airplane mode is enabled, where "1" = airplane mode enabled, "0" = not enabled
dndboolAndroid only) A boolean value indicating if “do not disturb” setting is enabled, where
"1" = do not disturb enabled,
"0" = not enabled.
attsint(iOS 14 + only) An integer passed to represent the app's app tracking authorization status, where

0 = not determined
1 = restricted
2 = denied
3 = authorized
bluetoothboolA boolean value indicating if the device is connected to bluetooth where
"1" = connected to bluetooth
“0” = not connected to bluetooth
"device": {
    "dnt": 2,
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_1_2 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12B440 Safari/600.1.4",
    "ip": "8.8.8.8",
    "geo": {
        "lat": 0,
        "lon": 0,
        "country": "USA",
        "region": "CA",
        "city": "Mountain View",
        "zip": "94040",
        "type": 2 // 1- GPS, 2- IP address
    },
    "carrier": "Google",
    "language": "en",
    "make": "Apple",
    "model": "iphone",
    "os": "iOS",
    "osv": "8",
    "connectiontype": 2, // 0 -Unknown, 1- Ethernet, 2 - WIFI, 3 -Cellular Network – Unknown Generation
    "devicetype": 1, // 1 - Mobile/Tablet
    "ifa": "1E2DFA89-47FD-9941-DF1FC4E6484C",
    "ext": {
        "airplane": 0,
        "batterylevel": 8, // 100-85% = 8 , 84-70% = 7, 69-55% = 6, 54-40% = 5, 39-25% = 4, 21-10% = 3, 9-5% = 2, < 5% = 1  
        "batterysaver": 1,
        "bluetooth": 1,
        "charging": 0,
        "darkmode": 0,
        "dnd": 0, // 0- Do Not Disturb disabled, 1- Do Not Disturb enabled
        "headset": 0, //0- No headset connected, 1- Headset connected
        "inputLanguage": [
            "en"
        ],
        "ringmute": 0, // 0- Mute, 1- Ring
        "diskspace": 1821, //MB of data
        "totaldisk": 128000 //MB of data
    }
},

Definition of Geo Device

AttributeDescriptionType
latLatitude from -90.0 to +90.0, where negative is southFloat
longLongitude from -180.0 to +180.0, where negative is westFloat
typeType - 1 - represents directly passed from device. 2 - Ip derivedInteger
utcoffsetLocal time as the number +/- of minutes from UTCinteger
accuracyEstimated location accuracy in meters; recommended when lat/lon are specified and derived from a device’s location services (i.e., type = 1). Note that this is the accuracy as reported from the device. Consult OS specific documentation (e.g., Android, iOS) for exact interpretationInteger
lastfixThe time accuracy of the location. The number of seconds since the location was retrieved. Format is in total number of seconds.Integer
ipserviceEnrichment providerInteger
metroZip code of the deviceString
zipZIP or postal codestring
CountryCountry code using ISO-3166-1-alpha-3String
RegionRegion code using ISO-3166-2; 2-letter state code if USAString
CityCity using United Nations Code for Trade & Transport Locations. See Appendix A for a link to the codesString
ext.ispInternet Service Provider nameString
ext.orgInternet Service Provider name.String
"device": {
    "dnt": 2,
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_1_2 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12B440 Safari/600.1.4",
    "ip": "8.8.8.8",
    "geo": {
        "lat": 0,
        "lon": 0,
        "country": "USA",
        "region": "CA",
        "city": "Mountain View",
        "zip": "94040",
        "type": 2, // 1- GPS, 2- IP address
        "utcoffset": 120,
        "accuracy": 400,
        "ipservice": 2,
        "ext": {
        	"isp":"Google",
        	"org":"Google"
        }
    },
    "carrier": "Google",
    "language": "en",
    "make": "Apple",
    "model": "iphone",
    "os": "iOS",
    "osv": "8",
    "connectiontype": 2, // 0 -Unknown, 1- Ethernet, 2 - WIFI, 3 -Cellular Network – Unknown Generation
    "devicetype": 1, // 1 - Mobile/Tablet
    "ifa": "1E2DFA89-47FD-9941-DF1FC4E6484C",
    "ext": {
        "airplane": 0,
        "batterylevel": 8, // 100-85% = 8 , 84-70% = 7, 69-55% = 6, 54-40% = 5, 39-25% = 4, 21-10% = 3, 9-5% = 2, < 5% = 1  
        "batterysaver": 1,
        "bluetooth": 1,
        "charging": 0,
        "darkmode": 0,
        "dnd": 0, // 0- Do Not Disturb disabled, 1- Do Not Disturb enabled
        "headset": 0, //0- No headset connected, 1- Headset connected
        "inputLanguage": [
            "en"
        ],
        "ringmute": 0, // 0- Mute, 1- Ring
        "diskspace": 1821, //MB of data
        "totaldisk": 128000 //MB of data
    }
},

Definition of the User Object

FieldScopeType
idstring; recommendedExchange-specificID for the user.
genderstringGender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown).
keywordsobjectComma separated list of keywords, interests, or intent.
.....
"user":{  
      "id":"78550233-77fc-5ba8-8bff-f6a1809344eb",
      "gender":"m",
      "keywords":"sports, paid user",
   },

.....

Sample Bid Request

{  
   "id":"4fc8acc7-6bb2-489d-7547-d3291547f17c",
   "imp":[  
      {  
         "id":"46600265-e3a4-44dd-7114-49d21405cacf",
        "banner": {
             "w": 320, "h": 50, 
             "pos": 1,
             "btype": [ 4 ],
             "battr": [ 14 ],
             "api": [ 3 ]
								},
         "bidfloor":0.01,
         "bidfloorcur":"USD"
      }
   ],
 "app":{  
      "id":"1004844",
      "name":"Countabc",
      "bundle":"628677149",
      "storeurl":"https://itunes.apple.com/....", 
      "cat":[  
         "IAB18"
      ],
      "keywords":"shopping", 
      "ver":"10.1", 
      "publisher":{  
         "id":"1028",
         "name":"Count LTD"
      }
   },
   "device":{  
      "dnt":1,
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1_2 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12B440 Safari/600.1.4",
      "ip":"8.8.8.8",
      "geo":{  
         "lat":0,
         "lon":0,
         "country":"USA",
         "region":"CA",
         "city":"Mountain View",
         "zip":"94040",
         "type":2
      },
      "carrier":"Google",
      "language":"en",
      "make":"Apple",
      "model":"iphone",
      "os":"iOS",
      "osv":"8",
      "connectiontype":2,
      "devicetype":1,
      "ifa":"1E2DFA89-47FD-9941-DF1FC4E6484C",
      "ext": {
        "airplane": 0,
        "batterylevel": 8,
        "batterysaver": 1,
        "bluetooth": 1,
        "charging": 0,
        "darkmode": 0,
        "dnd": 0,
        "headset": 0,
        "inputLanguage": [
            "en"
        ],
        "ringmute": 0,
        "diskspace": 1821,
        "totaldisk": 128000
    }  
   },
  "user":{  
      "id":"78550233-77fc-5ba8-8bff-f6a1809344eb",
      "gender":"m",
      "keywords":"sports, paid user"
   },
   "at":2,
   "tmax":100,
   "allimps":0,
   "cur":[  
      "USD"
   ],
   "bcat":[  
      "IAB1-1",
      "IAB18",
      "IAB1",
      "IAB14",
      "IAB24",
      "IAB17",
      "IAB15",
      "IAB22",
      "IAB20",
      "IAB13",
      "IAB9-7",
      "IAB1",
      "IAB12",
      "IAB6",
      "IAB3",
      "IAB3",
      "IAB14-1",
      "IAB5",
      "IAB7"
   ]
}

OpenRTB Response

The structure and contents of the Bid Response are the same as in the OpenRTB standard. The difference is how ad creative is returned.

BidResponse Object

FieldScopeType
idstring; requiredID of the bid request to which this is a response.
seatbidobject arrayArray of seatbid objects; 1+ required if a bid is to be made.
bididstringBidder generated response ID to assist with logging/tracking.
curstring; default “USDBid currency using ISO-4217 alpha codes. PN accepts on USD.
nbrinteger optionalReason for not bidding. Refer to OpenRTB Spec

Definition of Seat Bid Object

FieldScopeType
bidobject array; requiredArray of 1+ Bid objects (Section 4.2.3) each related to an impression. Multiple bids can relate to the same impression
seatstringID of the bidder seat on whose behalf this bid is made.
groupinteger; default 00 = impressions can be won individually; 1 = impressions must be won or lost as a group.

Definition of the Bid Object

FieldScopeTitle
idstring; requiredBidder generated bid ID to assist with logging/tracking.
impidstring; requiredID of the Imp object in the related bid request.
pricefloat; requiredBid 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).
adidstringID of a preloaded ad to be served if the bid wins.
nurlstringWin notice URL called by the exchange if the bid wins; optional means of serving ad markup.Please check Billing section for proper implementation.
admstring; requiredmeans of conveying ad markup in case the bid wins
adomainstring array,
required
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.Required for standard size ad formats.
bundlestringBundle or package name (e.g., com.foo.mygame) of the app being advertised, if applicable; intended to be a unique ID across exchanges.
iurlstringURL without cache-busting to an image that is representative
of the content of the campaign for ad quality/safety checking.
cidstringCampaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.
cridstringCreative ID to assist with ad quality checking. Needs to be unique per creative and cant not be re cycled.
catstring arrayIAB content categories of the creative
attrinteger arraySet of attributes describing the creative.
dealidstringReference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal. Required for PMP

🚧

Important checks

DSP´s integrating with PN ad server MUST keep in mind following points -

  • Build your bidder to comply with the PubNative OpenRTB 2.3 spec.
  • Impression trackers must be packed inside the adm object.
  • Passing nurl is mandatory.
  • Impressions confirmation window on PN ad server is 1hour. So we recommend DSP to have the same on their end to avoid discrepancies. In case of any questions please contact your Account Manager

Sample Response

{
  "id": "d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
  "bidid": "pbnvrtb-10048",
  "cur": "USD",
  "seatbid": [
    {
      "bid": [
        {
          "impid": "1a430de0-b222-412e-4c05-d6ab8115825a",
          "price": 0.071396679621748,
          "nurl": "http://pubnative-east.com/ads/notify.php?siteid=pbnvrtb1004844&adid=4ace572c&deviceid=1E2DFA89-496A-9931-EF1FC3C33A41&earnings=${AUCTION_PRICE}&impid=d7470a5f1a75-4bf6-4c8250abd49e8bb8&ip=8.8.8.8&countryCode=US&apikey=pbnvrtb&device=iPhone&os=8.1&mach=&ni=0&appid=667728512&adG roup=GameofWar_FireAge_iPhone_US&ourprice=0.071396679621748&adom=&seg=W10%3D&adgroupID=66323&campaignID=1 23395&creativeID=4ace572c¬ifyid=bd471f8e191410c8cc80d7469758ad9d&nb=0&rc=&ra=G0T0a0W00.1C00OG0003100000P0 04Qb0000000000n00000&sp=&ssrv=www1011&tzofse=0&impid=2015052014509627587ddba4a3bb1174c19f0acdb0af5391857e &carrier=WIFI&cg=TEST&at=2&bp=0.071396679621748&creativeID=4ace572c&aid=1E2DFA89-496A-9931EF1FC3C33A41&cf=2",
          "id": "pbnvrtb-1004844-d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
          "iurl": "http://platform.com/promote/mock/72c",
          "adomain": [ "advertiserdomain.com" ],
          "attr": [ 1, 2, 3, 4 ],
          "crid": "ce572c",
          "cid": "3395",
          "adm": "<iframe src=\"http://mobile123.info/kroznik-us-160530/320x50?networkId=42&publisherId=appcoach_1105_32466__com.forshared\" width=\"320\" height=\"50\" frameBorder=\"0\" scrolling=\"no\" style=\"border:0\"></iframe><img src='http://rtb-useast.ezmob.com/imp?i=E1G2aNMWXt4_0' alt=' ' style='display:none'><img src='http://rtb2.vashoot.com/imp?i=QNmodXd5aqs_0' alt=' ' style='display:none'><img src=\"http://us-e-node14.rtbadtrading.com/?t=win&b=${AUCTION_PRICE}&ob=0.46282&ds=4&cd=c73b0900340f2bb58f0b477269ddb8fa\" border=\"0\" width=\"1\" height=\"1\"><div style=\"display:none\"><img src=\"http://tr.pubnative.net/impression?aid=1004319&t=S5dFwqxKcQI5eWkc67nNhAaoHHW2XqtzJF_HeadIZMxuB9Kkx-AuPM1Rhp18r4jcNsVxs-mEFClFwT8E_pfJ5903CS7LaOj1Eodi4LZr2ETIDx5G8cI3zYFssNWSSlh32891pZWAQJgi603H3dGVjFyytRiNv1uGnr2WKJuTU6jYsm2MJkv3XGu6zohIfcUMCLeoYA0mMEp1HEmfSlSNwzqsfob9wFm3SJOhEybwWNA_lTVJPzi6yrSYPO67m9MxsJQPGMbCnGjb1byobcJgE1YQjvAm8yvUKqdyGFQQt4Pfv3kMXqwKeUPFEteaqU8uQV_MFmWsPmBLBVOBXxolTbDQ7Yqfa2bVd0V8DXGj4tW6Ei_DsgbaE1JRKQqFghAxdTx4I9vyXNlhDvsAJKs2e1GhEiVwjA_QwK0LgWox9oByzz6-MKHesTU48hc44ktyv-RpgI0CbPi7s6cOraUqngUk3SwkoylYvtVjluwpWeX77MDEKekLJMH1bRSILq8kV4j8i8vBahs1fcXBYZw2ar6da4jrLMJd-J5ITZ5PiisLggSnvUuPvWN-cwZMsHNEL_AMKCTLR4sxuVTppMsPt-K1IlwjRc-Qeoa8o6VV_lnPxjneA1xmITklj_IAMQRhJqvroRIUSzTFB3NyS7hDiAY8cCW1CbKaKkCYJD63LJvEj-gWSxK3r7GAFm2IkLHXTwgkMd5SWQOwb2qnTT0f_o4DrojR35XB7ummTYm6-fegpQjS27HDgLIXXcDk3lw-_c9OXJH6rjzHufuwdm_tYo0sXxv9ievD0w9uJo0Bbzo8ojp2Wo4IJgWqZhvoChtGHi0&tl=835&ap=${AUCTION_PRICE}&px=1\"/></div>"
        }
      ]
    },
    {
      "seat": "abc1abc"
    }
  ]
}