Important Note on No Bid/Error Responses

Please make sure that you always respond with HTTP 204 ("No Content") in case of a no bid response! Other no bid response types are considered invalid and can incur performance issues.


Bid Request Object Specifications

Object: BidRequest 

Field
Scope
Type
Default
Description
Smaato Mapping

id 

required

string

-

Unique ID of the bid request, provided by the exchange.

Random alphanumeric value. See BidRequestId

imp

required

objects array

-

Array of Imp objects representing the impressions offered. At least 1 Imp object is required.

Single Imp object

site

recommended for websites

object-

Details via a Site object about the publisher’s website. Only applicable and recommended for websites.

Site object

app

recommended for native appsobject-

Details via an App object about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps.

App object

device

recommended    

object-

Details via a Device object about the user’s device to which the impression will be delivered.

Device object

user

recommendedobject-

Details via a User object about the human user of the device; the advertising audience.

User object
testoptionalinteger0Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test modeN/A

at    

optionalinteger2

Auction type, where 1 = First Price, 2 = Second Price Plus. Exchange-specific auction types can be defined using values greater than 500.  

  • None - if Line Item is Preferred Deal
  • 2 (Second Price Auction) - in other cases

tmax

optionalinteger-

Maximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline.

N/A

wseat     

optionalstring array-

Whitelist of buyer seats (e.g., advertisers, agencies) allowed to bid on this impression. IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. Omission implies no seat restrictions.

N/A
allimpsoptionalinteger0Flag 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.0

cur

optionalstring array-

Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies.

N/A

bcat

optionalstring array-

Blocked advertiser categories using the IAB content categories. Refer to Content Categories.

Contains the combination of two sources of blocked categories.

  • Blocked categories from publisher Line Item
  • Blocked categories from Configuration in Database (OpenRTBBlockedIabCategories property)

badv

optionalstring array-

Block list of advertisers by their domains (e.g., “ford.com”).

Blocked domains from publisher Line Item e.g. company1.com, company2.com.
bappoptionalstring array-Blocklist of applications by their platform-specific exchange independent application identifiers. On Android, these should be bundle or package names (e.g., com.foo.mygame). On iOS, these are numeric IDs.N/A 

regs

optionalobject-

A Regs object that specifies any industry, legal, or governmental regulations in force for this request.

Regulations object

ext

optionalobject-

Placeholder for exchange-specific extensions to OpenRTB.

Bid Request Extension object

Back to table of contents

Object: Impression     

Field
Scope
Type
Default
Description
Smaato Mapping

id

required      

string      


-

A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).

Since we always have one unique impression object, this value is always 1.

banner   

required for banner impressions      

object   


-

A Banner object required if this impression is offered as a banner ad opportunity.

Banner object

video

required for video impressions

object   


-

A Video object required if this impression is offered as a video ad opportunity.

Video object
audiorequired for audio impressionsobject-An Audio object required if this impression is offered as an audio ad opportunityN/A
nativerequired for native impressionobject-A Native object required if this impression is offered as a native ad opportunity.Native object
pmpoptionalobject-A Pmp object containing any private marketplace deals in effect for this impression.Pmp object

displaymanager

recommended for video and native apps     


string   


-

Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.  

This value is SOMA. SOMA stands for Smaato Open Mobile Advertising.

displaymanagerver     

recommended for video and native apps


string   


-

Version of ad mediation partner, SDK technology, or player responsible for renderingad(typically video or mobile). Used by some ad servers to customize ad code bypartner. Recommended for video and/or apps.

If the ad request comes thru an SDK, the SDK version will be denoted; otherwise, this field will be empty.

instl

optionalinteger0

1 = the ad is interstitial or full screen, 0 = not interstitial. This field is only set for incoming ad requests on API version 5.0.2 and above.

1 for Interstitial/full screen ads, 0 for all others.

tagid      

optional

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.

The ad request's Adspace ID (or placement ID) is transmitted here.

bidfloor    

optionalfloat0

Minimum bid for this impression expressed in CPM.     

N/A

bidfloorcur      

optional

string      


USD

Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.   

Smaato only transacts on USD.
clickbrowseroptionalinteger-Indicates the type of browser opened upon clicking the creative in an app, where 0 = embedded, 1 = native. Note that the Safari View Controller in iOS 9.x devices is considered a native browser for purposes of this attribute.N/A
secureoptionalint-

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.

  • if publisher request is secure (e.g. dfp request)
  • 0 for non secure request

iframebuster

optional

string array

-

Array of exchange-specific names of supported iframe busters.

N/A
expoptionalinteger-Advisory as to the number of seconds that may elapse between the auction and the actual impression. N/A

ext

optional

object

-

Placeholder for exchange-specific extensions to OpenRTB.

Impression Extension object

Back to table of content

Object: Banner 

Field
Scope
Type
Default
Description
Smaato Mapping

w      

recommended

integer      

-

Width in device independent pixels (DIPS). If no format objects are specified, this is an exact width requirement.Otherwiseitis a preferred width.

hrecommendedinteger-

Height in device independent pixels (DIPS). If no format objects are specified, this is an exact height requirement.Otherwiseitis a preferred height.

formatrecommendedobject array-

Array of format objects representing the banner sizes permitted. If none are specified,thenuse of the h and w attributes is highly recommended.

Array with single format object

wmax     

DEPRECATEDinteger-

NOTE: Deprecated in favor of the format array. Maximum width in device independent pixels (DIPS).

N/A

hmax      

DEPRECATEDinteger-

NOTE: Deprecated in favor of the format array. Maximum height in device independent pixels (DIPS).

N/A

wmin      

DEPRECATEDinteger-

NOTE: Deprecated in favor of the format array. Minimum width in device independent pixels (DIPS).

N/A

hmin      

DEPRECATEDinteger-

NOTE: Deprecated in favor of the format array. Minimum height in device independent pixels (DIPS).

N/A

id      

recommended when subordinate to a video object    


string-

Unique identifier for this 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.

N/A
btypeoptionalinteger arrayAll types are allowed

Blocked banner ad types. Refer to Banner Ad Types.

All the following values:

  1. XHTMLTextAd
  2. XHTMLBannerAd
  3. XHTMLJavaScriptAd

Except supported creative type by ad type. Refer to the mapping of supported ad types in Banner Ad Types.

battroptionalinteger arrayAll types are allowed

Blocked creative attributes. Refer to Creative Attributes.

Contains the combination of two sources of blocked attributes:

  • Blocked attributes from publisher Line Item
  •  comma-separated list as the SOMA configuration propertyOpenRTBBlockedAttributes(default value is: 1,3,5,6,8,9)
posoptionalinteger-

Ad position on screen. Refer to Ad Position.


Ad Position from Adspace.

Refer to Ad Position.

mimesoptionalstring array All types are allowed

Content MIME types supported. Popular MIME types may include “application/x-shockwave-flash”, “image/jpg”, and “image/gif”.

Adtypes (context: ValidAdTypes) that are not blocked. Refer to the mapping of supported ad types in  Banner Ad Types
If the text ad is supported then MIMEs supported are:

  • text/html
  • text/plain

If the banner ad is supported then MIMEs supported are:

  • image/jpeg
  • image/png
  • image/gif

If the javascript ad is supported then MIMEs supported are:

  • text/javascript
  • application/javascript 
topframeoptionalinteger-

Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes

N/A
expdiroptionalinteger arrayNot expandable

Directions in which the banner may expand. Refer to Expandable Direction.  

    


N/A
apioptionalinteger array-

List of supported API frameworks for this banner. (See Table  6.4 API Frameworks).  If an API is not explicitly listed it is assumed not to be supported. 

Depends on the MRAID version that the publisher is requesting:

  • MRAID 1 --> [3]
  • MRAID 2 --> [3, 5]
extoptionalobject-

Placeholder for exchange-specific extensions to OpenRTB.

N/A

Back to table of contents

Object: Video 

As per IAB specs, Smaato regards VAST impression event as the official signal that the impression is billable. Hence your Vpaid creative must trigger the <AdImpression> to signal an impression to the video player.

Field
Scope
Type
Default
Description
Smaato Mapping
mimesrequired

string array

-

Content MIME types supported. Popular MIME types may include “video/x-ms-wmv” for Windows Media and “video/x-flv” for Flash Video.

For iOS we send:

  • video/3gpp
  • video/mov
  • video/mp4
  • video/mp

For all other OSs, we send:

  • video/3gpp
  • video/mp4

When the api field has a value 2 meaning the incoming bid request is VPAID compatible then the following MIME type will be sent:

  • "application/javascript"
mindurationrequiredinteger-

Minimum video ad duration in seconds

5 by default.
maxdurationrequiredinteger-

Maximum video ad duration in seconds

60 by default.

protocols     

recommendedinteger array-

Array of supported video protocols. Refer to Video Bid Response Protocols. At least one supported protocol must be specified in either the protocol or protocols attribute.

We send values 2,3,5,6,7 depending on the Protocol version

protocol

DEPRECATEDinteger-

NOTE: Deprecated in favor of protocols. Supported video protocol. Refer to Video Bid Response Protocols. At least one supported protocol must be specified in either the protocol or protocols attribute.

N/A

w    

recommendedinteger-

Width of the video player in device independent pixels (DIPS).

hrecommendedinteger-

Height of the video player in device independent pixels (DIPS).

startdelayrecommendedinteger-

Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Refer to Video Start Delay for additional generic values. This field is only set for incoming ad requests on API version 5.0.2 and above.

0 (pre-roll), when videotype=instream-pre
-1 (mid-roll), when videotype=instream-mid
-2 (post-roll), when videotype=instream-post

linearityoptionalinteger-

Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed. Refer to Video Linearity.

Default set to LinearInStream ('1'). Can be overridden by API parameter 'linearity'
skipoptionalinteger-Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. If a bidder sends markup/creative that is itself skippable, the Bid object should include the attr array with an element of 16 indicating skippable video.

1, when the publisher will intend to provide the skip option

0, when the publisher will intend to not provide the skip option

skipminoptionalinteger0Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.N/A
skipafteroptionalinteger0Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.N/A
sequenceoptionalinteger-

If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.   



    


N/A

battr     

optionalinteger array

Assume all types are allowed

Blocked creative attributes. Refer to Creative Attributes.

Contains the combination of two sources of blocked attributes:

  • Blocked attributes from publisher Line Item
  •  comma-separated list as the SOMA configuration propertyOpenRTBBlockedAttributes(default value is: 1,3,5,6,8,9)
maxextendedoptionalintegerExtension not allowed

Maximum extended 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.

N/A
minbitrateoptionalintegerAny bitrate accepted

Minimum bit rate in Kbps.

250
maxbitrateoptionalintegerAny bitrate accepted

Maximum bit rate in Kbps.   

4000
boxingallowedoptionalinteger1

Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes.    

N/A
playbackmethodoptionalinteger arrayAll

Playback methods that may be in use. If none are specified, any method may be used. Refer to Video Playback Methods. Only one method is typically used in practice. As a result, this array may be converted to an integer in a future version of the specification.

N/A
deliveryoptionalinteger arrayAll

Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported. Refer to Content Delivery Methods

N/A
posoptionalinteger- Ad position on screen. Refer to Ad Position.


Ad Position from Adspace

See Ad Position.

companionadoptionalobjects array-

Array of Banner objects if companion ads are available.

 
Contains the Banner Object

api   

optionalinteger array-

List of supported API frameworks for this impression. (See Table 6.4 API Frameworks).  If an API is not explicitly listed it is assumed not to be supported.

Contains 2 when the API Frameworks supported by the inventory is VPAID 2.0

companiontype   

optionalinteger array-

Supported VAST companion ad types. Refer to VAST Companion Types. Recommended if companion Banner objects are included via the companionad array.

Contains an array of VAST Companion Types
extoptionalobject-

Placeholder for exchange-specific extensions to OpenRTB. This field is only set for incoming ad requests on API version 5.0.2 and above.

Contains information if video type is outstream or rewarded. In other cases SOMA won't send an ext object.

Back to table of contents

Object: Native  

Field
Scope
Type
Default
Description
Smaato Mapping
requestrequiredString-Request payload complying with the Native Ad Specification.For more details see Native.request below.
verrecommendedString1.1Version of the Dynamic Native Ads API to which request complies; highly recommended for efficient parsing.We'll send the value according to the latest standard; currently 1.1.
apioptionalarray of integerNoneList of supported API frameworks for this banner. (See Table 6.4 API Frameworks). If an API is not explicitly listed, it is assumed not to be supported.

Depends on the MRAID version that the publisher is requesting:

  • MRAID 1 --> [3]
  • MRAID 2 --> [3, 5]
battroptionalarray of integerAll types are allowed

Blocked creative attributes. See Table 5.3 Creative Attributes. If blank, assume all types are allowed.

Default value is: 1,3,5,8,9 (globally set in the exchange) - see Table 5.3 Creative Attributes.

extoptionalobject-Placeholder for exchange-specific extensions to OpenRTB.N/A

Back to table of contents



Object: Format 

Field
Scope
Type
Description
Smaato Mapping
wrecommendedintegerWidth in device independent pixels (DIPS).
hrecommendedintegerHeight in device independent pixels (DIPS).
extoptionalObjectPlaceholder for exchange specific extensions to OpenRTB.N/A

Back to table of contents

Object: Site 

Field
Scope
Type
Default
Description
Smaato Mapping

id      

recommendedstring-

Exchange-specific site ID.

"Application ID" (ID of the website) of the ad request.
nameoptionalstring-

Site name (may be masked at publisher’s request).

Web page/property name.
domainoptionalstring-

Domain of the site, used for advertiser side blocking. For example, “foo.com”. 


catoptionalstring array-

Array of IAB content categories of the site. Refer to Content Categories.

Array of IAB categories.
sectioncatoptionalstring array-

Array of IAB content categories that describe the current section of the site. Refer to Content Categories.

N/A
pagecatoptionalstring array-

Array of IAB content categories that describe the current page or view of the site. Refer to Content Categories.

N/A
pageoptionalstring-

URL of the page where the impression will be shown.

N/A
refoptionalstring-

Referrer URL that caused navigation to the current page.

Referrer URL
searchoptionalstring-

Search string that caused navigation to the current page.  

Query string
mobileoptionalinteger-Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yesN/A

privacypolicy    

optionalinteger-

Specifies whether the site has a privacy policy. “1” means there is a policy. “0” means there is not.

N/A
publisheroptionalobject-

Details about the Publisher of the site.


See Publisher Object
contentoptionalobject-

Details about the Content within the site.


N/A
keywordsoptionalstring-

Comma separated list of keywords about the site.

ALTERNATE Representation: string array.

Keyword list.
extoptionalobject-

Placeholder for exchange-specific extensions to OpenRTB.

N/A

Back to table of contents

Object: App 

FieldScopeTypeDefaultDescriptionSmaato Mapping
id      recommended     string-Application ID on the exchange.Application ID
name      optional    string-Application name (may be masked at publisher’s request).      
 
App name (blank if hidden).
bundle    optional  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 a numeric ID.Bundle ID.
domain      optionalstring-Domain of the application (e.g., “mygame.foo.com”).      
 
URL
storeurl      optionalstring-For QAG 1.5 compliance, an app store URL for an installed app should be passed in the bid request.      
 
App store URL.
cat      optionalstring array-Array of IAB content categories for the overall application.  See Content Categories.    
 
Array of IAB categories.
sectioncat      optionalstring array-Array of IAB content categories for the current subsection of the app.  See Content Categories.     N/A
pagecat      optionalstring array-Array of IAB content categories for the current page/view of the app.  See  Content Categories.      
 
N/A
ver    optionalstring-Application version.      
 
N/A
privacypolicy   optionalinteger-Indicates if the app has a privacy policy, where 0 = no, 1 = yes.      
 
N/A
paid      optionalinteger-“1” if the application is a paid version; else “0” (i.e., free).   
 
N/A
publisher      optionalobject-Details about the Publisher
 
See Publisher Object
content      optionalobject-Details about the Content
 
N/A
keywords    optionalstring-

List of keywords describing this app in a  comma separated string.

ALTERNATE  Representation: string array.     

Keyword list.
extoptionalobject-Placeholder for exchange-specific extensions to OpenRTB.
 
N/A

Back to table of contents

Object: Publisher 

FieldScopeTypeDefaultDescriptionSmaato Mapping
idoptionalstring-Publisher ID on the exchange.     Publisher ID.
nameoptionalstring-Publisher name (may be masked at publisher’s request).     Publisher name (blank if hidden).
catoptionalstring array-Array of IAB content categories for the  publisher.  See Table  6.1 Content Categories.  N/A
domainoptionalstring-Publisher’s highest level domain name, for example “foopub.com”.  N/A
extoptionalobject-Placeholder for exchange-specific extensions to OpenRTBN/A

Back to table of contents

Object: Content      

FieldScopeTypeDefaultDescriptionSmaato Mapping
idoptionalstring-ID uniquely identifying the content      
 
N/A
episodeoptionalinteger-Content episode number (typically applies to video content).      
 
N/A
titleoptionalstring-Content title.       
Video examples: “Search Committee” (television) or “A New Hope” (movie) or “Endgame” (made for web)
Non-­‐video example:  “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article)      
 
N/A
seriesoptionalstring-Content series.       
Video examples: “The Office” (television) or “Star Wars” (movie) or “Arby ‘N’ The Chief” (made for web)       
Non-­‐video example: “Ecocentric” (Time magazine blog)
N/A
seasonoptionalstring-Content season. E.g., “Season 3” (typically applies to video content).      
 
N/A
urloptionalstring-Original URL of the content, for buy-­‐side contextualization or review.     
 
N/A
cat   optionalstring array-Array of IAB content categories for the content.  See Table  6.1 Content Categories.      
 
N/A
videoqualityoptionalinteger-Video quality per the IAB’s classification. See Table 6.14 Video Quality.       
 
N/A
keywords    optionalstring-Comma separatedlist of keywords describing the content. ALTERNATE Representation: string array.      
 
N/A
contentrating    optionalstring-Content rating (e.g., MPAA)N/A
userratingoptionalstring-User rating of the content (e.g., number of stars, likes, etc.).      
 
N/A
context     optionalinteger-Specifies the type of content (game, video, text, etc.).  See Table 6.13  Content Context.     N/A
livestream      optionalinteger-Is content live? E.g., live video stream, live blog.“1” means content is live. “0” means it is not live.N/A
sourcerelationship      optionalinteger-1 for “direct”; 0 for “indirect”     N/A
producer    optionalobject-See Producer ObjectN/A
len   optionalinteger-Length of content (appropriate for video or audio) in seconds.      
 
N/A
qagmediaratingoptionalinteger-Media rating of the content, per QAG guidelines. See Table 0 QAG Media Ratings for list of possible values.
 
N/A
embeddableoptionalinteger-From QAG Video Addendum. If content can be embedded (such as an embeddable video player) this value should be set to “1”.  If content cannot  be embedded, then this should be set to “0”.      
 
N/A
languageoptionalstring-Language of the content. Use alpha-­‐2/ISO 639-­‐1 codes.N/A
ext    optionalobject-Placeholder for exchange-specific extensions to OpenRTB.N/A

Back to table of contents

Object: Producer 

FieldScopeTypeDefaultDescriptionSmaato Mapping
id      optional     string   -Content producer or originator ID. Useful if content is syndicated, and may be posted on a site using embed tags.N/A
name    optionalstring-Content producer or originator name (e.g., “Warner Bros”).  N/A
catoptionalstring array-Array of IAB content categories for the content producer. See Table 6.1  Content Categories.N/A
domainoptionalstring-URL of the content producer.     N/A
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.N/A

Back to table of contents

Object: Device     

FieldScopeTypeDefaultDescriptionSmaato Mapping
uarecommended   string-Browser user agent string.     User agent string.
georecommended if IP is not suppliedobject-Geography as derived from the device’s location services (e.g., cell tower triangulation, GPS) or IP address.  See Geo Object.
 
See Geo Object
dntrecommendedinteger
Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not trackCurrently, null will be sent.
lmtrecommended    integer   -"Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.0 for unrestricted tracking, 1 for restricted tracking according to Apple/Google guidelines.
iprecommended if geo object is not suppliedstring-IPv4 address closest to device.    IPv4 address.
ipv6optionalstring-IP address in IPv6.IPv6 address.
devicetypeoptionalinteger-Return the device type being used. See Table  6.16 Device Type.    Always 1 (for mobile/tablet).
makeoptionalstring-Device make (e.g., “Apple”).    Device make (e.g., “Apple”).    
modeloptionalstring-Device model (e.g., “iPhone”).    Device model (e.g., “iPhone”).    
os    optionalstring-Device operating system (e.g., “iOS”).     Device operating system (e.g., “iOS”).     
osvoptionalstring-Device operating system version (e.g., “3.1.2”).  Device operating system version (e.g., “3.1.2”).  
hwvoptionalstring-Hardware version of the device (e.g., “5S” for iPhone 5S).N/A
hoptionalinteger-Physical height of the screen in pixelsN/A
woptionalinteger-Physical width of the screen in pixelsN/A
ppioptionalinteger-Screen size as pixels per linear inch.N/A
pxratiooptionalfloat-The ratio of physical pixels to device independent pixels.N/A
jsoptionalinteger-“1” if the device supports JavaScript; else “0”.    “1” if the device supports JavaScript; else “0”.    
geofetchoptionalinteger-Indicates if the geolocation API will be available to JavaScript code running in the banner, where 0 = no, 1 = yes.N/A
flashveroptionalstring-Return the Flash version detected.     N/A
languageoptionalstring-Browser language; use alpha-­‐2/ISO 639-­‐1 codes.    N/A
carrieroptionalstring-Carrier or ISP derived from the IP address. Should be specified using Mobile Network Code (MNC)       
http://en.wikipedia.org/wiki/Mobile_Network_Code      
MCC or MNC value.
connectiontypeoptionalinteger-Return the detected data connection type for the device.'WLAN only' or Connection, Carrier & Name (if detected).
ifaoptionalstring-Native identifier for advertisers; an opaque ID assigned by the device or browser for use as an advertising identifier. (e.g. Apple's IFA, Android's Advertising ID, etc)     

The value depends on the device's operation system:

  • IDFA for iPhone
  • GoogleAdId for Android
  • BlackberryId for RIM
  • WpId (Windows Phone ID) for Windows Phone or Mobile
didsha1optional    string-SHA1 hashed device ID; IMEI when available, else MEID or ESN. OpenRTB’s preferred method for device ID hashing is SHA1.    hashed Device ID
didmd5optionalstring-MD5 hashed device ID; IMEI when available, else MEID or ESN. Should be interpreted as case insensitive.

hashed Device ID

dpidsha1optionalstring-SHA1 hashed platform-­‐specific ID (e.g., Android ID or UDID for iOS). OpenRTB’s preferred method for device ID hash is SHA1.hashed Device ID
dpidmd5optionalstring-MD5 hashed platform-­‐specific ID (e.g., Android ID or UDID for iOS). Should be interpreted as case insensitive.    hashed Device ID
macsha1optionalstring-SHA1 hashed MAC address of the device.     hashed Device ID
macmd5optionalstring-MD5 hashed MAC address of the device.hashed Device ID
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.N/A

Back to table of contents

Object: Geo    

FieldScopeTypeDefaultDescriptionSmaato Mapping
latoptionalfloat      -Latitude from -90.0 to +90.0, where negative is south.latitude
lon    optionalfloat      -Longitude from -180.0 to +180.0, where negative is west.  longitude
typeoptionalinteger-Source of location data; recommended when passing lat/lon. Refer to Location Type.
 

1 (GPS Location Service)

2 (IP)

3 (User Provided)

accuracyoptionalinteger-Estimated 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.N/A
lastfixoptionalinteger-Number of seconds since this geolocation fix was established. Note that devices may cache location data across multiple fetches. Ideally, this value should be from the time the actual fix was taken.Number of seconds.
ipserviceoptionalinteger-Service or provider used to determine geolocation from IP address if applicable (i.e., type = 2).See IPLocationService
country      optionalstring-Country using ISO-­‐3166-­‐1 Alpha-­‐3. See IPLocationService
region      optionalstring-Region using ISO 3166-­‐2. See IPLocationService
regionfips104   optionalstring-Region of a country using FIPS 10-­‐4 notation (alternative to ISO 3166-­‐2).N/A
metro    optionalstring-Pass the metro code (see http://code.google.com/apis/adwords/docs/appendix/metrocodes.html). Metro codes are similar to but not exactly the same as Nielsen DMAs.      Metro code (See IPLocationService)
city    optionalstring-City using United Nations Code for Trade and Transport Locations (http://www.unece.org/cefact/locode/service/location.htm).      City (See IPLocationService)
zip    optionalstring-Zip/postal code.  ZIP code.
utcoffsetoptionalinteger-Local time as the number +/- of minutes from UTC.N/A
extoptionalobject-Placeholder for exchange-specific extensions to OpenRTB  N/A

Back to table of contents

Object: User 

FieldScopeTypeDefaultDescriptionSmaato Mapping
idrecommended (or buyeruid)string-Unique consumer ID of this user on the exchange.Unique exchange user identifier.
buyeruid     recommended (or id)string-Buyer’s user ID for this user as mapped by exchange for the buyer.  N/A
yoboptional      integer-Year of birth as a 4-­‐digit integer.Year of birth.
genderoptionalstring-Gender as “M” male, “F” female, “O” Other. (Null indicates unknown).    F, M, O or null for unknown.
keywordsoptionalstring-

Comma separated list of keywords of consumer interests or intent.

ALTERNATE Representation: string array.

Keyword list
customdataoptionalstring-If supported by the exchange, this is custom data that the bidder had stored in the exchange’s cookie. The string may be in base85 cookie safe characters, and be in any format. This may useful for storing user features. Note: Proper JSON encoding must be used to include “escaped” quotation marks.     Smaato Cookie User ID.
geooptionalobject-Home geo for the user (e.g., based off of registration data); this is different from the current location of the access device (that is defined by the geo object embedded in the Device Object); see Device Object.

geo{

lat,

long,

type

}

dataoptionalobjects array-Additional user data. Each Data object represents a different data source.   
 
N/A
extoptionalobject-Placeholder for exchange-specific extensions to OpenRTB  
 
N/A

Object: User.ext

Field

Scope

Type

Default

Description

Smaato Mapping
consentoptionalstring-Contains the data structure developed by the GDPR Consent Working Group under the auspices of IAB Europe.N/A

GDPR - user consent string

The user consent string is optional, but highly recommended if the request is subject to GDPR regulations (i.e., Regs.ext.gdpr = 1). The default sense of consent under GDPR is “opt-out” and as such, an omitted consent string in a request subject to GDPR would need to be interpreted as equivalent to the user fully opting out of all defined purposes for data use by all parties.1

Back to table of contents

Object: Data 

FieldScopeTypeDefaultDescriptionSmaato Mapping
idoptionalstring-Exchange specific ID for the data provider.      N/A
nameoptionalstring-Data provider name.     N/A
segmentoptionalobjects array-Array of segment objects.      N/A
extoptionalobject-Placeholder for exchange-specific extensions to OpenRTB.N/A

Back to table of contents

Object: Segment     

Field
Scope
Type
Default
Description
Smaato Mapping
idoptionalstring-

ID of a data provider’s segment applicable to the user.

N/A
nameoptionalstring-

Name of a data provider’s segment applicable to the user.

N/A
valueoptionalstring-

String representation of the data segment value.

N/A
extoptionalobject-

Placeholder for exchange-specific extensions to OpenRTB.

N/A

Back to table of contents

Object: Regs 

Field
Scope
Type
Default
Description
Smaato Mapping
coppaoptionalinteger-

Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.

0 or 1
extoptionalobject-Placeholder for exchange-specific extensions to OpenRTB.N/A

Object Regs.ext

Field

Scope

Type

Default

Description

Smaato Mapping
gdproptionalinteger-Signaled whether or not the request is subject to GDPR via the extension attribute “gdpr” which is an optional integer that indicates: 0 = No, 1 = Yes.0 or 1

Back to table of contents


Object: Pmp 

FieldScopeTypeDefaultDescriptionSmaato Mapping
private_auctionoptionalinteger0Indicator 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.
 

1 - private auction

0 - open auction

deals    optionalobjects array-Array of Deal objects that convey the specific deals applicable to this impression.
 
See Direct Deals Object
extoptionalobject-This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification.N/A

Back to table of contents

Object: Deal     

FieldScopeTypeDefaultDescriptionSmaato Mapping
idrequiredstring-A unique identifier for the direct deal.     Deal ID
bidflooroptionalfloat0Bid floor for this impression (in CPM of bidfloorcur).      
 
Floor price
bidfloorcuroptionalstringUSDIf bid floor is specified and multiple currencies supported per bid request, then currency should be specified here using ISO-­-4217 alphabetic codes. Note, this may be different from bid currency returned by bidder, if this is allowed on an exchange.     USD
atoptionalinteger-Auction type. If “1”, then first price auction. If “2”, then second price auction. If “3”, the passed bidfloor indicates the apriori agreed upon deal price. Additional auction types can be defined as per the exchange’s business rules.    
  • SecondPrice(2) for PrivateExchange

  • AgreedDealPrice(3) for PreferredDeal

wseatoptionalstring array-Array of buyer seats allowed to bid on this  Direct Deal. Seats are an optional feature of an exchange. For example,  [“4”,”34”,”82”,”45”] indicates that only advertisers using these exchange seats are allowed to bid on this direct deal.N/A
wadomainoptionalstring array-Array of advertiser domains allowed to bid on this Direct Deal. For example, [“advertiser1.com”,”advertiser2.com”] indicates that only the listed advertisers are allowed to bid on this direct deal.      
 
N/A
ext    optionalobject-Placeholder for exchange-specific extensions to OpenRTB.N/A

Back to table of contents

Object: BidRequestExtension 

Field

Scope

Type

Description

Smaato Mapping

carriername

optional

String

Custom field with the SOMA internal carriername (that is the the name we obtain from the soma db or the GeoIPCache Not the Carriername we log)

Carrier Name

Back to table of contents


Object: ImpressionExtension 

Field
Scope
Type
Description
Smaato Mapping
strictbannersizeoptionalintegerCustom field with following values:
  • 1 if the banner size to be treated strictly
  • 0 (default value) if the DSP can return ads smaller than banner size

For standard ads, this value will be 1 or 0.Defaultis 0.

For native ads, this value is 0.

Back to table of contents

Bid Response Object Specifications

Object: Bid Response   

FieldScopeTypeDefaultDescription
idrequiredstring-ID of the bid request.  
seatbidoptionalobjects array-Array of seatbid objects.   
bididoptionalstring-Bid response ID to assist tracking for bidders. This value is chosen by the bidder for cross-­‐reference.
curoptionalstring-Bid currency using ISO-­‐4217 alphabetic codes; default is “USD”.
customdataoptionalstring-This is an optional feature, which allows a bidder to set data in the exchange’s cookie. The string may be in base85 cookie safe characters, and be in any format. This may be useful for storing user features. Note: Proper JSON encoding must be used to include “escaped” quotation marks.
nbr    optionalinteger-Reason for not bidding. See Table 6.19  NoBid Reason Codes.    
 
extoptionalobject-Placeholder for exchange-specific extensions to OpenRTB  

Back to table of contents

Object: Seat Bid    

FieldScopeTypeDefaultDescription
bidrequiredobjects array-Array of bid objects; each bid object relates to an imp object in the bid request. Note that, if supported by an exchange, one imp object can have many bid objects.
seatoptionalstring-ID of the bidder seat on whose behalf this bid is made.
groupoptionalinteger-“1” means impressions must be won-­-lost as a group; default is “0”.      
 
extoptionalobject-Placeholder for exchange-specific extensions to OpenRTB  
 

Back to table of contents

Object: Bid 

FieldScopeTypeDefaultDescription
id      requiredstring-ID for the bid object chosen by the bidder for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat. 
impid      requiredstring-ID of the impression object to which this bid applies.
pricerequiredfloat-Bid price in CPM.  WARNING/Best Practice Note: Although this value is a  float, OpenRTB strongly suggests using integer math for accounting to avoid rounding errors.    
adid     optionalstring-ID that references the ad to be served if the bid wins.
nurl    optionalstring-Win notice URL. Note that ad markup is also typically, but not necessarily, returned via this URL.   
admoptionalstring-Actual ad markup. XHTML if a response  to a banner object, or VAST XML if a response to a video object, or JSON if response is native object.
adomain      optionalstring array-Advertiser’s primary or top-­‐level domain for advertiser checking. This can be a list of domains if there is a  rotating creative. However, exchanges  may mandate that only one landing domain is allowed.
Iurl     optionalstring-Sample image URL (without cache busting) for content checking.
cidoptionalstring-Campaign ID or similar that appears within the ad markup.
cridoptionalstring-Creative ID for reporting content issues or defects. This could also be used as a reference to a creative ID that is posted with an exchange.
attroptionalinteger array-Array of creative attributes. See Table 5.3 Creative Attributes.
dealidoptionalstring-A unique identifier for the direct deal associated with the bid. If the bid is associated and in response to a dealid in the request object it is required in the response object.
hoptional
-Height of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin optional fields it is recommended that the response bid contains this field to signal the size of ad chosen.
woptional
-Width of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin optional fields it is recommended that the response bid contains this field to signal the size of ad chosen.
extoptionalobject-Placeholder for exchange-specific extensions to OpenRTB  

Back to table of contents

Native API Version 1.1 Documentation


Multiple Main Image in the Bid Request

Native Ads Bid Request Changes: Depending on our Publisher Request, we can send multiple main images asset request in the same Bid Request. The maximum main images which we will request for the same ad placement will be limited to 3 in total.

Request 

Field
Scope
Type
Default
Description
Smaato Mapping
veroptionalString 1.1Request payload complying with the Native Ad Specification.1.1
context
recommendedinteger

The context in which the ad appears.

See Table of Context IDs below for a list of supported context types.

Not Applicable anymore (because of the latest Native Ads release in July)

contextsubtype

optionalinteger

A more detailed context in which the ad appears.

See Table of Context SubType IDs below for a list of supported context subtypes.

Not yet applicable.

plcmttype
recommendedinteger1

The design/format/layout of the ad unit being offered.

Currently always 1.

plcmtcnt
optional
1

The number of identical placements in this Layout. Refer to Section 8.1 Multiplacement Bid

Requests for further detail.
Currently always 1.
seq
optional
0

0 for the first ad, 1 for the second ad, and so on. Note this would generally NOT be used in combination with plcmtcnt - either you are auctioning multiple identical placements (in which case plcmtcnt>1, seq=0) or you are holding separate auctions for distinct items in the feed (in which case plcmtcnt=1, seq=>=1).

Currently always 0.
assets
requiredobjects array

An array of Asset Objects. Any bid response must comply with the array of elements expressed in the bid request.

See Native assets
layoutrecommended in 1.0, to be deprecatedinteger
The Layout ID of the native ad unit.N/A
adunitrecommended in 1.0, to be deprecatedinteger
The Ad unit ID of the native ad unit.N/A

Back to table of contents

Assets 

Field
Scope
Type
Default
Description
Smaato Mapping

id     

required

integer      


Unique asset ID, assigned by
exchange. Typically a counter for the array.

Rather than sending a fixed Asset ID for each asset type, Smaato will generate IDs based on existing assets of current Native Bid Request. With this change, we will be able to request multiple Main Image assets in bid request.

requiredoptionalinteger

title object = 1 (required)

img object = 1 (required)

video object = not supported yet

data object = 1 (required)

Always 0 (Changed from always 1 during the Native Ads Release in July 2018)
title* recommendedobject
Title object for title assets. See TitleObject definition.See Title Object
img* recommendedobject

Image object for image assets.

See ImageObject definition.
See Image object
video* recommendedobject
Not yet applicable.Not yet applicable.
data* recommendedobject

See Data object

We include two asset instances into the Request with this field - one asset for descriptions, the other for CTA Texts.

extoptional

This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this

specification
N/A

*Each asset object may contain only one of title, img, data or video.

Back to table of contents

Title Object 

 Field
Scope
Type
Default
Description
Smaato Mapping

len    

required

integer      


Maximum length of the text in the title element. Recommended to be 25, 90, or 140.

140 by default.
extoptionalobject

This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification.

N/A

Back to table of contents

Image Object 

 Field
Scope
Type
Default
Description
Smaato Mapping

type   

optional

integer      



Type ID of the image element supported by the publisher. The publisher can display this information in an appropriate format.

1: Icon

3: Main

woptionalinteger
Width of the image in pixels.N/A
wminrecommendedinteger

The minimum requested width of the image in pixels. This option should be used for any rescaling of images by the client. Either w or wmin should be transmitted. If only w is included, it should be considered an exact requirement.

Values for:

  • Icon: 50
  • Image: 627
hoptionalinteger
Height of the image in pixels.N/A
hminrecommendedinteger

The minimum requested height of the image in pixels. This option should be used for any rescaling of images by the client.  Either h or hmin should be transmitted. If only h is included, it should be considered an exact requirement.

Values:

  • Icon: 50
  • Image: 627
mimesoptionalarrays of string

Whitelist of content MIME types supported. Popular MIME types include, but are not limited to “image/jpg”  “image/gif”. Each implementing Exchange should have their own list of supported types in the integration docs.  See Wikipedia's MIME page for more information and links to all IETF RFCs.If blank, assume all types are allowed.

N/A
 extoptionalobject

This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification.

N/A

Back to table of contents

Data Object 

 Field
Scope
Type
Default
Description
Smaato Mapping

type    

required

integer      


Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format. See Data Asset Types table for commonly used examples.

  • 2 for desc 
  • 12 for ctatext

Back to table of contents

Example of Native ad request

Native ad request
{
    "ver": "1.1",
    "plcmttype": 1,
    "plcmtcnt": 1,
    "seq": 0,
    "assets": [
        {
            "id": 1,
            "required": 0,
            "title": {
                "len": 90
            }
        },
        {
            "id": 2,
            "required": 0,
            "image": {
                "type": 1,
                "wmin": 50,
                "hmin": 50
            }
        },
        {
            "id": 3,
            "required": 0,
            "image": {
                "type": 3,
                "wmin": 627,
                "hmin": 627
            }
        },
        {
            "id": 4,
            "required": 0,
            "data": {
                "type": 12,
                "len" : 15
            }
        },
        {
            "id": 5,
            "required": 0,
            "data": {
                "type": 2
                "len" : 140
            }
        {
            "id": 6,
            "required": 0,
            "data": {
                "type": 3
                "len" : 0
            }
        {
            "id": 7,
            "required": 0,
            "image": {
                "type": 3,
                "wmin": 627,
                "hmin": 627
            }
         }
    ]
}


Back to table of contents

Reference Lists/Enumerations

Content Categories       

Smaato ValueRTB ValueDescription



Back to table of contents

Banner Ad Types 

ValueDescription
1

XHTML text ad. (usually mobile)      

2

XHTML banner ad.  (usually mobile)

3

JavaScript ad; must  be valid  XHTML  (i.e., script  tags included).

4 Iframe

Back to table of contents

Creative Attributes 

ValueDescription
1Audio Ad (Auto Play)       
2Audio Ad (User Initiated)      
3Expandable (Automatic)      
4Expandable (User Initiated -­‐ Click)      
5Expandable (User Initiated -­‐ Rollover)      
6In-­‐Banner Video Ad (Auto Play)      
7In-­‐Banner Video Ad (User Initiated)      
8Pop (e.g., Over, Under, or upon Exit)      
9Provocative or Suggestive Imagery
10Shaky, Flashing, Flickering, Extreme Animation, Smileys     
11Surveys     
12Text Only
13User Interactive (e.g., Embedded Games)  
14Windows Dialog or Alert Style  
15Has audio on/off button     
16Ad can be skipped (e.g., skip button on preroll video)     

Back to table of contents

API Frameworks

ValueDescription
1VPAID  1.0
2

VPAID  2.0   

3

MRAID-­1   

4ORMMA
5MRAID-2

Back to table of contents

Ad Position       

ValueDescription
0Unknown
1Above the fold
2

DEPRECATED  -­‐   May or may not be immediately visible depending  on screen  size and resolution. 

3

Below  the fold 

4Header
5Footer
6Sidebar
7Fullscreen

Back to table of contents

Video Linearity   

ValueDescription
1

Linear/In-­‐stream   

2

Non-­‐Linear/Overlay      

Back to table of contents

Video Bid Response Protocols  

ValueDescription
1VAST 1.0
2VAST 2.0
3VAST 3.0
4

VAST 1.0  Wrapper      

5

VAST 2.0  Wrapper

6

VAST 3.0  Wrapper

Back to table of contents

Video Playback Methods       

ValueDescription
1Auto-­‐play sound on
2

Auto-­‐play sound  off      

3

Click-­‐to-­‐play      

4

Mouse-­‐over      

Back to table of contents

Video Start Delay    

ValueDescription
0

Pre-­‐roll     

-1Generic mid-­‐roll
-2

Generic Post-­‐roll 

Back to table of contents

Expandable Direction       

ValueDescription
1Left
2

Right   

3Up
4Down
5Fullscreen

Back to table of contents

Content Delivery Methods 

ValueDescription
1Streaming
2Progressive

Back to table of contents

Content Context     

ValueDescription
1Video (a video file or stream that is being watched by the user, including (Internet) television broadcasts)
2Game (an interactive software game that is being played by the user)
3Music (an audio file or stream that is being listened to by the user, including (Internet) radio broadcasts)
4Application (an interactive software application that is being used by the user)
5Text (a document that is primarily textual in nature that is being read or viewed by the user, including web page, ebook, or news article)
6Other (content type unknown or the user is consuming content which does not fit into one of the categories above)
7Unknown

Back to table of contents

Video Quality 

ValueDescription
0Unknown
1

Professionally Produced   

2Prosumer
3

User  Generated (UGC) 

Back to table of contents

Location Type        

ValueDescription
1GPS/Location Services
2IP Address
3

User provided  (e.g.,  registration  data)      

Back to table of contents

Device Type 

ValueDescription
1

Mobile/Tablet    

2

Personal Computer      

3Connected TV
4Phone
5Tablet
6

Connected Device   

7Set Top Box

Back to table of contents

VAST Companion Types       

ValueDescription
1Static Resource
2HTML Resource
3iframe Resource

Back to table of contents

QAG Media Ratings  

ValueDescription
1

All  Audiences

2

Everyone over 12

3Mature  Audience

Back to table of contents

NoBid Reason Codes     

ValueDescription
0Unknown Error
1Technical Error
2Invalid Request
3Known Web spider
4Suspected  Non-­‐Human Traffic
5Cloud, Data center, or Proxy IP
6

Unsupported  Device

7

Blocked Publisher or Site

8

Unmatched user

Back to table of contents

IP Location Service  

ValueDescription
1

Ip2Location

2

Neustar

3MaxMind

Back to table of contents