OpenRTB Request & Response Structure

For standard, native and video formats PubNative supports OpenRTB versions 2.x.

Bid Request Specifications

The bid request consists of the top-level bid request object, at least one impression object, and may
optionally include additional objects providing impression context.

BidRequest Object

The top-level object is denoted as "BidRequest". The top-level BidRequest object contains a series of subordinate objects that provide detailed data to potential buyers.

AttributeTypeDescription
idstring; requiredUnique ID of the bid request, provided by the exchange.
impobject; requiredUnique ID of the bid request, provided by the exchange.
siteobjectPubNative will send this for mobile websites.
appobjectPubNative 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.
testinteger; defaultIndicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode.
atintegerAuction type, where 1 = First Price, 2 = Second Price
PubNative 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. PubNative only allows bidding in USD
bcatstring arrayBlocked advertiser categories using the IAB content categories. DSP need to respect bcat to align with PubNative publishers and exchange wide settings
badvstring arrayBlock list of advertisers by their domains (e.g., “ford.com”). Typically designated by publishers
sourceobjectA Source object that provides data about the inventory source and which entity makes the final decision.
regsobjectA Regs object that specifies any industry, legal, or governmental regulations in force for this request.

Definition of the Source Object

AttributeTypeDescription
fdinteger; optionalEntity responsible for the final impression sale decision, where
0 = exchange, 1 = upstream source.
pchainstring; recommendedPayment ID chain string containing embedded syntax
described in the TAG Payment ID Protocol v1.0.
ext.omidpnstringIdentifier of the Open Measurement SDK integration. The default value for PubNative’s Hybid SDK is “Pubnativenet”.
ext.omidpvstringVersion of the Open Measurement SDK integration.
ext.schainobject; recommendedThis object represents both the links in the supply chain as well as an indicator whether or not the supply chain is complete.

📘

NOTE

Depending on the integration, PubNative will send pchain, omidpn, omipv fields and schain object under BidRequest.Source object, and/or under BidRequest.ext object.

Definition of the Source.ext.schain Object

AttributeTypeDescription
verstring; requiredThe version of the supply chain specification in use
completeinteger; requiredFlag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app, or another medium of the inventory, where 0 = no, 1 = yes
nodesobject array;
required
Array of SupplyChainNode objects in the order of the chain. In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction.
nodes.asistring; requiredCanonical domain name of the SSP, Exchange, Header
Wrapper, etc system that bidders connect to.
nodes.sidstring; requiredThe identifier associated with the seller or reseller account
within the advertising system.
nodes.ridstringThe OpenRTB RequestId of the request as issued by this
seller.
nodes.hpintegerIndicates whether this node will be involved in the flow of payment for the inventory.

Definition of the Regs Object

AttributeTypeDescription
coppaintegerFlag indicating if this request is subject to the COPPA
regulations established by the USA FTC, where 0 = no, 1 = yes.
ext.gdprintegerFlag that indicates whether or not the request is subject to
GDPR regulations 0 = No, 1 = Yes, omission indicates
Unknown.
ext.consentstringWhen GDPR regulations are in effect this attribute contains
the Transparency and Consent Framework’s Consent String
data structure.
ext.us_privacystringCommunicates signals regarding consumer privacy under US
privacy regulation. See US Privacy String specifications.

Definition of the Impression Object

AttributeTypeDescription
idstring; requiredA unique identifier for this impression within the context of the bid request.
metricobject arrayAn array of Metric object. Details listed here.
bannerobject; required if banner adBanner object; Details are listed below.
videoobject; required if video adVideo object; Details are listed below
nativeobject; required if native adNative object; Details are listed below
pmpobjectContains any private marketplace deals in effect for this impression. Details are listed below
displaymanagerstringName of ad mediation partner, SDK technology, or player
responsible for rendering ad. For PubNative’s Hybid SDK, “HyBid” value will be passed.
displaymanagerverstringVersion of ad mediation partner, SDK technology, or player
responsible for rendering ad. For PubNative’s Hybid SDK, relevant sdk version will be sent.
instlinteger; default 0Indicates if the ad is interstitial or not. 1 = the ad is interstitial or full screen, 0 = not interstitial.
tagidstringIdentifier for specific ad placement or ad tag that was used to
initiate the auction.
bidfloorfloatMinimum bid for this impression expressed in CPM.
bidfloorcurstring; default “USD”Currency specified using ISO-4217 alpha codes. Pubnative only support USD
secureintegerFlag 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 nonsecure
HTTP support can be assumed.
rwddinteger; default 0Indicates whether the user receives a reward for viewing the ad
ad, where 0 = no, 1 = yes.
extobjectPlaceholder for exchange-specific extensions.

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
skadnobjectAn object that provides the relevant fields used to control the SKOverlay. The attribute is only present if the SDK and OS versions (iOS 14 and above) support SKOverlay. More information and further details about support can be found here.

Definition of the Metric Object

AttributeTypeDescription
typestring; requiredType of metric being presented using exchange curated string names, for example: “click_through_rate"
valuefloat; requiredNumber representing the value of the metric. Probabilities must be in the range 0.0 – 1.0.
vendorstring;
recommended
Source of the value using exchange curated string names which should be published to bidders a priori. If the exchange itself is the source versus a third party, “EXCHANGE” is recommended.

📘

About Metric Object

We will send the Metric object in both BidRequest.Imp and BidRequest.Imp.ext objects.

Examples of type values that we will be populating for specific integrations are “click_through_rate" and "viewability"

Sample of CTR Viewability

 "imp": [
        {
          "id": "12068b09-361d-4b00-9a18-e8fcb9cf1d2b",
          "metric": [
            {
              "type": "click_through_rate",
              "value": 0.00263,
              "vendor": "EXCHANGE"
            },
            {
              "type": "viewability",
              "value": 1,
              "vendor": "integralads.com"
            }

Definition of the Banner Object

The presence of a "Banner" object as a subordinate of the Imp object indicates that this impression is offered
as a banner type impression.

AttributeTypeDescription
formatobject arrayArray of format objects representing the banner sizes
permitted.
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

Definition of the Video Object

The presence of a Video object as a subordinate of the Imp object indicates that this impression is offered
as a video type impression. This object represents an in-stream video impression.

AttributeTypeDescription
mimesstring array; requiredContent ​MIME ​types ​supported.
Popular MIME types may include “video/x-ms-wmv” for Windows
Media​ ​and​ ​“video/x-flv”​ ​for​ ​flash​ ​video
mindurationinteger; recommendedMinimum ​video ​ad ​duration ​in ​seconds
maxdurationinteger; recommendedMaximum ​video ​ad ​duration ​in ​seconds
protocolsinteger array; recommendedArray ​of ​supported ​video ​bid ​response ​protocols.
At​ ​least​ ​one​ ​supported​ ​protocol​ ​must​ ​be​ ​specified​ ​in either​ ​the​ ​protocol​ ​or​ ​protocols​ ​attribute.
winteger; recommendedWidth ​of ​the ​video ​player ​in ​pixels.
hinteger; recommendedHeight ​of ​the ​video ​player ​in ​pixels.
startdelayinteger; recommendedIndicates the start delay in seconds for pre-roll, mid-roll, or post-roll ​ad ​placements.
linearityintegerIndicates ​if ​the ​impression ​must ​be ​linear, ​nonlinear, ​etc. If​ ​none​ ​specified,​ ​assume​ ​all​ ​are​ ​allowed.
sequenceintegerIf multiple ad impressions are offered in the same bid
request, the sequence number will allow for the
coordinated ​delivery ​of ​multiple ​creatives.
battrinteger arrayBlocked ​creative ​attributes.
maxextendedintegerMaximum ​extended ​video ​ad ​duration ​if ​extension ​is
allowed. ​If ​blank ​or ​0, ​extension ​is ​not ​allowed.
If​ ​-1,​ ​extension​ ​is​ ​allowed,​ ​and​ ​there​ ​is​ ​no​ ​time​ ​limit​ ​imposed.​ ​If greater​ ​than​ ​0,​ ​then​ ​the​ ​value​ ​represents​ ​the​ ​number​ ​of​ ​seconds​ ​of extended​ ​play​ ​supported​ ​beyond​ ​the​ ​maxduration​ ​value.
maxbitrateintegerMaximum ​bit ​rate ​in ​Kbps.
Exchange​ ​may​ ​set​ ​this​ ​dynamically​ ​or​ ​universally​ ​across​ ​their​ ​set of​ ​publishers
boxingallowedintegerIndicates ​if ​letter-boxing ​of ​4:3 ​content ​into ​a ​16:9 ​window
is ​allowed, ​where ​0 ​= ​no, ​1 ​= ​yes.
Default​ ​=​ ​1
playbackmethodinteger arrayAllowed ​playback ​methods. ​If ​none ​specified, ​assume ​all
are ​allowed.
deliveryinteger arraySupported ​delivery ​methods ​(e.g., ​streaming, ​progressive).
If ​none ​specified, ​assume ​all ​are ​supported.
companionadobject arrayArray ​of ​Banner ​objects, ​if ​companion ​ads ​are ​available
apiinteger arrayList ​of ​supported ​API ​frameworks ​for ​this ​impression.
If​ ​an​ ​API​ ​is​ ​not​ ​explicitly​ ​listed,​ ​it​ ​is​ ​assumed​ ​not​ ​to​ ​be​ ​supported.
companiontypeinteger arraySupported ​VAST ​companion ​ad ​types.
skipinteger; recommendedIndicates if the player will allow the video to be skipped, where 0 = no, 1 = yes.
skipmininteger; recommendedDefault 0 Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.
skipafterinteger;
default 0
Number of seconds a video must play before skipping is
enabled; only applicable if the ad is skippable.
extobjectPlaceholder ​for ​exchange-specific ​extensions ​to ​OpenRTB.
plcmtintegerVideo placement type for the impression. 1 = instream, 2 = companion, 3 = Interstitial, 4 = standalone

📘

About Rewarded Video placements

Please note that if the placement is for Rewarded Video, the following parameters and values will be added to the Bid Request body:

  • BidRequest.imp.rwdd = 1
  • BidRequest.imp.video.ext.rewarded = 1
  • BidRequest.imp.video.ext.videotype = "rewarded"
  • BidRequest.imp.video.ext.skip = 0
  • BidRequest.imp.video.skip = 0

Definition of the Native Object

The presence of a Native object as a subordinate of the Imp object indicates that this impression is offered
as a native type impression. This object represents a native type impression.

AttributeTypeDescription
requeststring;requiredRequest payload complying with the Native Ad Specification.
verstring; requiredVersion of the Native Markup version in use.
adunitrecommendedAd unit in integer
apiinteger arrayList of supported API frameworks for this impression.
plcmtcntinteger; optionalThe number of identical placements
seqinteger;optional0 for the first ad, 1 for the
second ad, and soon. Note this would generally NOT be used in combination with plcmtcnt -
high case plcmtcnt>1, seq=0) r you are holding separate
feed (in which case plcmtcnt=1, seq=>=1)
assetsobject; requiredAny objects bid response must comply with the array of elements expressed in the bid request. Must be passed as URL encoded string.

Definition of the Asset Object

AttributeTypeDescription
idinteger; requiredUnique asset ID, assigned by exchange. Typically a counter for the array.
requiredinteger; optionalSet to 1 if asset is required
titleobject ;requiredTitle object for title assets.TitleObject definition.
imgobject; requiredImage object for image assets.See ImageObject definition.
dataobject; requiredData object for brand name, description, ratings, prices etc. See DataObject definition.

Definition of the Title Object

AttributeTypeDescription
lenrequiredMaximum length of the text in the title element.
Recommended to be 25

Definition of the Image Object

AttributeTypeDescription
typeinteger; requiredType ID of the image element supported by the publisher. Pubnative supports
1,3
1- Icon
3- Banner
winteger; recommendedWidth of the image in pixels.
In case of icon - 80
In case of banner - 1200
The above mentioned sizes are recommended. PubNative does not post process images, we allow images of any size.
hinteger; recommendedHeight of the image in pixels.
In case of icon - 80
In case of banner - 627
The above mentioned sizes are recommended. PubNative does not post process images, we allow images of any size.

Definition of the Pmp Object

This object is the private marketplace container for direct deals. The actual deals are represented as a collection of Deal objects.

AttributeTypeDescription
private_auctioninteger; requiredIndicator of auction eligibility to seats named in the Direct Deals object,
where
0 = all bids are accepted,
1 = bids are restricted to the deals specified and the terms thereof.
dealsobjectArray of Deal objects that convey the specific deals
applicable to this impression

Definition of the Deal Object

AttributeTypeDescription
idstring; requiredPubnative - specific app ID.
bidfloorfloatMinimum bid for this impression expressed in CPM.
atintegerOptional override of the overall auction type of the bid
request, where 1 = First Price, 2 = Second Price

Definition of the App Object

FieldScopeType
idstring;
recommended
Pubnative - specific app ID.
namestringApp name in the relevant appstore
bundlestringA 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 a numeric ID.
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.

Definition of the Publisher Object

AttributeTypeDescription
idstringExchange-specific publisher id. Corresponds to a seller_id of a seller in the Pubnative’s sellers.json file.
namestringPublisher name (may be aliased at the publisher’s request).
domainstringHighest level domain of the publisher

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.
lmtinteger;
recommended
“Limit Ad Tracking” signal commercially endorsed (e.g., iOS,
Android), where 0 = tracking is unrestricted, 1 = tracking must
be limited per commercial guidelines.
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
hintegerPhysical height of the screen in pixels.
wintegerPhysical width of the screen in pixels.
ppiintegerScreen size as pixels per linear inch.
hwvstringHardware version of the device
pxratiofloatThe ratio of physical pixels to device independent pixels.
jsintegerSupport for JavaScript, where 0 = no, 1 = yes
geofetchintegerIndicates if the geolocation API will be available to JavaScript
code running in the banner, where 0 = no, 1 = yes.
languagestringBrowser language using ISO-639-1-alpha-2.
carrierstringCarrier or ISP. “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)
extobjectPlaceholder for exchange-specific extensions.

Definition of the Device Ext Object

📘

About Device Extension Object

The Device Extension object contains fields that can be used by buyers for "contextual app targeting". For more information about "Contextual App Targeting", please refer to this page.

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

Definition of Geo Device

AttributeTypeDescription
latfloatLatitude from -90.0 to +90.0, where negative is south
lonfloatLongitude from -180.0 to +180.0, where negative is west
typeintegerType - 1 - represents directly passed from device. 2 - Ip derived
utcoffsetintegerLocal time as the number +/- of minutes from UTC
accuracyintegerEstimated 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 interpretation
lastfixintegerThe time accuracy of the location. The number of seconds since the location was retrieved. Format is in total number of seconds.
ipserviceintegerEnrichment provider
metrostringZip code of the device
zipstringZIP or postal code
CountryStringCountry code using ISO-3166-1-alpha-3
RegionstringRegion code using ISO-3166-2; 2-letter state code if USA
CitystringCity using United Nations Code for Trade & Transport Locations. See Appendix A for a link to the codes
ext.ispstringInternet Service Provider name
ext.orgstringInternet Service Provider name.

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.
extobjectPlaceholder for exchange-specific extensions.

Definition of User Ext Object

FieldScopeType
sessiondurationintegerThe total duration of time a user has spent so far in a specific app session expressed in seconds.
impdepthintegerThe count of impressions for a specific placement type in a given app session. The impression depth is reset once the session ends.
ageratingstringApp or screen content rating.
eidsobjectsContains the Extended identifiers object.


Bid Response Specifications

The bid response consists of the top-level bid response object and optional objects that depict the specific bids. The structure and contents of the Bid Response are the same as in the OpenRTB standard, for standard, native & video ad formats. The difference is how ad creative is returned.

An empty HTTP response, a malformed response or a response that contains no actual bids will be interpreted as no-bid.

📘

For a Native Bid Response, all Demand Side integrations must include the 'native' node within the ADM attribute.

Definition of BidResponse Object

AttributeTypeDescription
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. PubNative accepts on USD.
nbrinteger optionalReason for not bidding. Refer to OpenRTB Spec

Definition of Seat Bid Object

AttributeTypeDescription
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

📘

About Bid Object

Bid object contains win notice url (nurl), billing notice url (burl) and loss notice url (lurl). For more information on:

  • Win Notification & Minimum Bid to Win, please refer here.
  • Bid Loss Notification, please refer here
AttributeTypeDescription
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.
burlstringBilling notice URL called by the PubNative when a winning bid becomes billable.
nurlstringWin notice URL called by the PubNative if the bid wins. Please check this page for proper implementation & further information.
lurlstringLoss notice URL called by the PubNative when a bid is known to
have been lost. Please check this page for proper implementation & further information.
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.
apisinteger arrayList of supported APIs for the markup. If an API is not explicitly
listed, it is assumed to be unsupported. Refer to List: API
Frameworks in AdCOM 1.0.
apiintegerAPI required by the markup if applicable. Refer to List: API
Frameworks in AdCOM 1.0. (A value(s) either in “api” as an integer, or in “apis” as an array should be sent in bid response)
protocolinteger; recommended for videoVideo response protocol of the markup if applicable. Refer to
List: Creative Subtypes - Audio/Video in AdCOM 1.0.
dealidstringReference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal. Required for PMP
wintegerWidth of the creative in device independent pixels
hintegerHeight of the creative in device independent pixels
extobjectPlaceholder for specific extensions

Definiton of Bid.ext.skadn (SKAdNetwork)

For more information about SKAdNetwork & SkOverlay please refer to the documentation here.

AttributeTypeDescription
versionstringVersion of skadnetwork supported. Always "2.0" or higher. Dependent on both the OS version and the SDK version.
networkstringAd network identifier used in signature. Should match one of the items in the skadnetids array in the request

(For example:"dsp1.skadnetwork")
campaignstringCampaign id compatible with Apple's spec. As of 2.0, should be an integer between 1 and 100, expressed as a string.

(For example: "75")
itunesitemstringid of advertiser's app in Apple's app store. Should match BidResponse.seatbid.bid.bundle

(For example: "5678")
fidelitiesObject arraySupports multiple fidelity types introduced in SKAdNetwork v2.2
noncestringAn id unique to each ad response. Refer to Apple's documentation for the proper UUID format requirements.
Note: With the release of SKAdNetowrk v2.2, this field is deprecated in favor of the BidResponse.seatbid.bid.ext.dkadn.fidelities
.nonce

(For example: "uaroa34u-a9de-01420004")
signaturestringSKAdNetwork signature as specified by Apple.

Note: With the release of SKAdNetwork 2.2, this field is deprecated in favor of the BidResponse.seatbid.bid.ext.skadn.fidelities.
signature to support multiple fidelity-types.

(For example: "MEQCIEQZRRyMyUXg==")
timestampstringUnix time in milliseconds string used at the time of signature.

Note: With the release of SKAdNetwork 2.2, this field is deprecated in favor of BidResponse.seatbid.bid.ext.skadn.fidelities.
timestamp to support multiple fidelity-types.

(For example: "1613406371")
sourceappstringid of publisher's app in Apple's app store. Should match BidRequest.imp.ext.skad.sourceapp

(For example: "123456789")
sourceidentifierstringA four-digit integer that ad networks define to represent the ad campaign. Used in SKAdNetwork 4.0+, replaces Campaign ID 'campaign'. DSPs must generate signatures in 4.0+ using the Source Identifier. Please refer to the SKAdNetwork 4 release notes for more details.
productpageidstringProduct Page id to direct to on click
skoverlayobjectSKOverlay auto present support

Definition of Bid.ext.skadn.skoverlay (SKOverlay)

For more information about SKAdNetwork & SkOverlay please refer to the documentation here

AttributeTypeDescription
presentbinaryHybid SDK needs to present the SKOverlay (1 = Yes, 0 = No)
delayint; default 0Delay in seconds before showing the overlay (0-60)
endcarddelayint; default 0Delay in seconds before showing the overlay on top of the end card (0-60).
Use -1 if you do not want to show the overlay on top of the end card
autocloseint; default 0Time in seconds to automatically dismiss the overlay (0-60).
Value of 0 means no automatic dismiss
dismissiblebinary; default 0Should the SKOverlay be dismissable by the user
posbinary;
default 1
Position of the overlay;
0 = bottom, 1 = bottom raised

Sample Request & Responses

Sample Banner 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",
            "displaymanager": "HyBid",
            "displaymanagerver": "2.0.0",
            "tagid": "1328491",
            "secure": 1
        }
    ],
    "app": {
        "id": "1328764",
        "name": "Countabc",
        "bundle": "com.countabc",
        "storeurl": "https://play.google.com/store/apps/details?id=com.countabc",
        "cat": [
            "IAB9"
        ],
        "keywords": "games",
        "ver": "10.1",
        "publisher": {
            "id": "1028",
            "name": "Count LTD",
            "domain": "https://countltd.com/support"
        }
    },
    "device": {
        "dnt": 0,
        "ua": "Mozilla/5.0 (Linux; Android 5.0.2; LG-V500 Build/LRX22G; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/95.0.4638.74 Safari/537.36",
        "ip": "8.8.8.8",
        "geo": {
            "lat": 40.2024,
            "lon": -21.2939,
            "country": "USA",
            "region": "CA",
            "city": "Mountain View",
            "zip": "94040",
            "type": 2
        },
        "carrier": "Mobile Carrier",
        "language": "en",
        "make": "Mobile",
        "model": "Mobile Model",
        "os": "Android",
        "osv": "12",
        "connectiontype": 2,
        "devicetype": 1,
        "ifa": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "gender": "m",
        "keywords": "sports, paid user",
        "ext":{
            "sessionduration": 1439,
            "impdepth": 123,
            "agerating": "PG-13"
        }
    },
    "source": {
        "pchain": "d641df8625486a7b:1007950",
        "ext": {
            "schain": {
                "ver": "1.0",
                "complete": 1,
                "nodes": [
                    {
                        "asi": "pubnative.net",
                        "sid": "1007950",
                        "rid": "2132da3ec6544048bf2d25c566d0dd49",
                        "hp": 1
                      }
                ]
            },
            "omidpn": "Pubnativenet",
            "omidpv": "1.4.3"
        }
    },
    "regs": {
        "coppa": 0,
        "ext": {
            "gdpr": 0,
            "consent": ""
        }
    },
    "at": 2,
    "tmax": 100,
    "allimps": 0,
    "cur": [
        "USD"
    ],
    "bcat": [
        "IAB1-1",
        "IAB22",
        "IAB7"
    ]
}

Sample Banner Response

{
    "id": "d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
    "bidid": "pbnvrtb-10048",
    "cur": "USD",
    "seatbid": [
        {
            "id": "1UARoaQytm",
            "seat": "512",
            "bid": [
                {
                    "impid": "1a430de0-b222-412e-4c05-d6ab8115825a",
                    "price": 0.07134,
                    "nurl": "http://platform.com/winnotice?impid=123;wp=${AUCTION_PRICE}",
                    "burl": "http://platform.com/burl?impid=123;wp=${AUCTION_PRICE}",
                    "lurl": "http://platform.com/bidloss?lossreason=${AUCTION_LOSS}",
                    "id": "pbnvrtb-1004844-d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
                    "adm": "<a href=\"http://platformserver.com/click?adid=creative3395&tracker=${CLICK_URL:URLENCODE}\"><img src=\"http://img1.pltfrm.com/impid=1a430d\"/></a>""iurl": "http://platform.com/pathtosampleimage/72c",
                    "adomain": [
                        "advertiserdomain.com"
                    ],
                    "cat": ["IAB12"],
                    "attr": [
                        1,
                        2,
                        3,
                        4
                    ],
                    "crid": "ce572c",
                    "cid": "creative3395"
                }
            ]
        }
    ]
}


Sample Video Request

{
    "id": "958e3f27-90f9-4183-be4f-bd350f7cc170",
    "imp": [
        {
            "id": "46600265-e3a4-44dd-7114-49d21405cacf",
            "video": {
                "mimes": [
                    "video/3gpp",
                    "video/3gpp2",
                    "video/mp4",
                    "video/quicktime",
                    "video/x-m4v"
                ],
                "minduration": 1,
                "maxduration": 120,
                "protocols": [
                    2,
                    3,
                    5,
                    6,
                    7,
                    8
                ],
                "w": 320,
                "h": 480,
                "linearity": 1,
                "skip": 1,
                "skipafter": 5,
                "skipmin": 5,
                "pos": 7,
                "companionad": [
                    {
                        "w": 320,
                        "h": 480,
                        "id": "1",
                        "pos": 7,
                        "vcm": 1
                    }
                ],
                "api": [
                    3,
                    5
                ],
                "companiontype": [
                    1,
                    2,
                    3
                ]
            },
            "displaymanager": "HyBid",
            "displaymanagerver": "2.0.0",
            "instl": 1,
            "tagid": "1328491",
            "bidfloor": 23.53,
            "bidfloorcur": "USD",
            "secure": 1,
            "rwdd": 0,
            "ext": {
                "hb": 0,
                "skadn": {
                    "version": "3.0",
                    "sourceapp": "net.pubnative.demo",
                    "skadnetids": [
                        "abcdefg12345.skadnetwork"
                    ],
                    "skadnetlist": {
                        "addl": [
                            "abcdefg12345.skadnetwork"
                        ]
                    },
                    "skoverlay": [
                        "dismissible",
                        "delay",
                        "present",
                        "pos",
                        "endcarddelay",
                        "autoclose"
                    ]
                }
            }
        }
    ],
    "app": {
        "id": "1328764",
        "name": "Countabc",
        "bundle": "com.countabc",
        "storeurl": "https://play.google.com/store/apps/details?id=com.countabc",
        "cat": [
            "IAB9"
        ],
        "keywords": "games",
        "ver": "10.1",
        "publisher": {
            "id": "1028",
            "name": "Count LTD",
            "domain": "https://countltd.com/support"
        }
    },
    "device": {
        "dnt": 0,
        "ua": "Mozilla/5.0 (Linux; Android 5.0.2; LG-V500 Build/LRX22G; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/95.0.4638.74 Safari/537.36",
        "ip": "8.8.8.8",
        "geo": {
            "lat": 40.2024,
            "lon": -21.2939,
            "country": "USA",
            "region": "CA",
            "city": "Mountain View",
            "zip": "94040",
            "type": 2
        },
        "carrier": "Mobile Carrier",
        "language": "en",
        "make": "Mobile",
        "model": "Mobile Model",
        "os": "Android",
        "osv": "12",
        "connectiontype": 2,
        "devicetype": 1,
        "ifa": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "gender": "m",
        "keywords": "sports, paid user",
        "ext": {
            "sessionduration": 1439,
            "impdepth": 123,
            "agerating": "PG-13"
        }
    },
    "source": {
        "pchain": "d641df8625486a7b:1007950",
        "ext": {
            "schain": {
                "ver": "1.0",
                "complete": 1,
                "nodes": [
                    {
                        "asi": "pubnative.net",
                        "sid": "1007950",
                        "rid": "2132da3ec6544048bf2d25c566d0dd49",
                        "hp": 1
                    }
                ]
            },
            "omidpn": "Pubnativenet",
            "omidpv": "1.4.3"
        }
    },
    "regs": {
        "coppa": 0,
        "ext": {
            "gdpr": 0,
            "consent": ""
        }
    },
    "test": 0,
    "at": 1,
    "tmax": 1987,
    "cur": [
        "USD"
    ],
    "badv": [
        "blockedadv.com"
    ],
}

Sample Video Response

{
    "id": "d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
    "bidid": "pbnvrtb-10048",
    "cur": "USD",
    "seatbid": [
        {
            "bid": [
                {
                    "impid": "1a430de0-b222-412e-4c05-d6ab8115825a",
                    "price": 0.07134,
                    "nurl": "http://platform.com/winnotice?impid=123;wp=${AUCTION_PRICE}",
                    "burl": "http://platform.com/burl?impid=123;wp=${AUCTION_PRICE}",
                    "lurl": "http://platform.com/bidloss?lossreason=${AUCTION_LOSS}",
                    "id": "pbnvrtb-1004844-d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
                    "adm": "<VASTAdTagURI><![CDATA[https://raw.githubusercontent.com/InteractiveAdvertisingBureau/VAST_Samples/master/VAST%203.0%20Samples/Inline_Companion_Tag-test.xml]]></VASTAdTagURI>",
                    "adomain": [
                        "advertiserdomain.com"
                    ],
                    "cat": [
                        "IAB12"
                    ],
                    "attr": [
                        1,
                        2,
                        3,
                        4
                    ],
                    "apis": [
                        3,
                        5,
                        7
                    ],
                    "protocol": 5,
                    "crid": "ce572c",
                    "cid": "creative3395",
                    "ext": {
                        "skadn": {
                            "version": "3.0",
                            "network": "abcdefg12345.skadnetwork",
                            "campaign": "53",
                            "itunesitem": "1382171002",
                            "fidelities": [
                                {
                                    "fidelity": 0,
                                    "nonce": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                                    "signature": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
                                    "timestamp": "1702313222"
                                }
                            ],
                            "sourceapp": "123456789",
                            "sourceidentifier": "sourceidentifier",
                            "productpageid": "productpageid",
                            "skoverlay": {
                                "present": 1,
                                "delay": 5,
                                "endcarddelay": 15,
                                "autoclose": 20,
                                "dismissible": 1,
                                "pos": 1
                            }
                        }
                    }
                }
            ]
        },
        {
            "seat": "abc1abc"
        }
    ]
}


Sample Native Request

{
    "id": "958e3f27-90f9-4183-be4f-bd350f7cc170",
    "imp": [
        {
            "id": "46600265-e3a4-44dd-7114-49d21405cacf",
            "native": {
                "request": "{\"ver\":\"1.1\",\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"data\":{\"type\":12}},{\"id\":2,\"required\":1,\"title\":{\"len\":100}},{\"id\":3,\"required\":1,\"img\":{\"type\":1,\"w\":80,\"h\":80}},{\"id\":4,\"required\":1,\"img\":{\"type\":3,\"w\":1200,\"h\":627}},{\"id\":5,\"data\":{\"type\":3}},{\"id\":6,\"required\":1,\"data\":{\"type\":2,\"len\":150}}]}",
                "ver": "1.1"
            },
            "displaymanager": "HyBid",
            "displaymanagerver": "2.0.0",
            "tagid": "BANNER",
            "bidfloor": 0.923,
            "bidfloorcur": "USD",
            "secure": 1,
            "rwdd": 0
        }
    ],
    "app": {
        "id": "1328764",
        "name": "Countabc",
        "bundle": "com.countabc",
        "storeurl": "https://play.google.com/store/apps/details?id=com.countabc",
        "cat": [
            "IAB9"
        ],
        "keywords": "games",
        "ver": "10.1",
        "publisher": {
            "id": "1028",
            "name": "Count LTD",
            "domain": "https://countltd.com/support"
        }
    },
    "device": {
        "dnt": 0,
        "ua": "Mozilla/5.0 (Linux; Android 5.0.2; LG-V500 Build/LRX22G; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/95.0.4638.74 Safari/537.36",
        "ip": "8.8.8.8",
        "geo": {
            "lat": 40.2024,
            "lon": -21.2939,
            "country": "USA",
            "region": "CA",
            "city": "Mountain View",
            "zip": "94040",
            "type": 2
        },
        "carrier": "Mobile Carrier",
        "language": "en",
        "make": "Mobile",
        "model": "Mobile Model",
        "os": "Android",
        "osv": "12",
        "connectiontype": 2,
        "devicetype": 1,
        "ifa": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "gender": "m",
        "keywords": "sports, paid user",
        "ext": {
            "sessionduration": 1439,
            "impdepth": 123,
            "agerating": "PG-13"
        }
    },
    "source": {
        "pchain": "d641df8625486a7b:1007950",
        "ext": {
            "schain": {
                "ver": "1.0",
                "complete": 1,
                "nodes": [
                    {
                        "asi": "pubnative.net",
                        "sid": "1007950",
                        "rid": "2132da3ec6544048bf2d25c566d0dd49",
                        "hp": 1
                    }
                ]
            },
            "omidpn": "Pubnativenet",
            "omidpv": "1.4.3"
        }
    },
    "regs": {
        "coppa": 0,
        "ext": {
            "gdpr": 0,
            "consent": ""
        }
    },
    "ext": {
        "hb": 1,
        "schain": {
            "ver": "1.0",
            "complete": 1,
            "nodes": [
                {
                    "asi": "pubnative.net",
                    "sid": "1008838",
                    "rid": "e81f99d2174b4f42ba4a0fadca1d12f6",
                    "hp": 1
                }
            ]
        },
        "omidpn": "pubnativenet",
        "omidpv": "1.4.8",
        "pchain": "d641df8625486a7b:1008838"
    },
    "test": 0,
    "at": 1,
    "tmax": 1987,
    "cur": [
        "USD"
    ],
    "badv": [
        "blockedadv.com"
    ],
}

Sample Native Response

📘

For a Native Bid Response, all Demand Side integrations must include the 'native' node within the ADM attribute.

{
    "id": "d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
    "bidid": "pbnvrtb-10048",
    "cur": "USD",
    "seatbid": [
        {
            "id": "1UARoaQytm",
            "seat": "512",
            "bid": [
                {
                    "impid": "1a430de0-b222-412e-4c05-d6ab8115825a",
                    "price": 0.03134,
                    "nurl": "http://platform.com/winnotice?impid=123;wp=${AUCTION_PRICE}",
                    "burl": "http://platform.com/burl?impid=123;wp=${AUCTION_PRICE}",
                    "lurl": "http://platform.com/bidloss?lossreason=${AUCTION_LOSS}",
                    "id": "pbnvrtb-1004844-d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
                    "adm": "{  \"native\": {    \"assets\" : [ {      \"id\" : 2,      \"title\" : {        \"text\" : \"This is a sample\"      }    }, {      \"id\" : 3,      \"img\" : {        \"w\" : 120,        \"h\" : 90,        \"url\" : \"https://platformimages.com/id=213214\"      }    }, {      \"id\" : 4,      \"img\" : {        \"w\" : 1066,        \"h\" : 800,        \"url\" : \"https://platformimages.com/id=213214\"      }    }}",
                    "adomain": [
                        "advertiserdomain.com"
                    ],
                    "cat": [
                        "IAB12"
                    ],
                    "attr": [
                        1,
                        2,
                        3,
                        4
                    ],
                    "w": 0,
                    "h": 0,
                    "crid": "ce572c",
                    "cid": "creative3395"
                }
            ]
        }
    ]
}