Click here to expand Version History!

Version History

3.1.102/03/2009MOAdded link to list of Mobile Network Codes (MNC). Updated sample XML response. Shortened introduction. Added examples to the HTML response. Parameter ‘carrier’ is not mandatory. section that describes the beacon support. Changes in the header forwarding section. Layout changes. development and production server URLs. the http header forwarding section. Added description to error code 42. instructions how to pass the UDID for iPhone apps. 
3.1.6. 12/10/2009MOChanges according to the new publisher portal and according to the automated rollout process. Included targeting parameter document. Minor changes. parameters for analytics. Added medium rectangle format. Minor changes. URLs are of the parameter section. New targeting parameters. Minor maintenance changes und updates. Section “OwnId” updated. Added privacy section. Video Ads. Rich Media Ad Format. Important: Enhanced usage of parameter “format”. Added new parameters “dimensions” and “formatstrict”. changes. Added multiline text ads (see XML response description). updates to the handling of unique IDs (UDID, ODIN etc.). Removed parameter “client”. Added Parameter “apiver” (mandatory). Parameter ‘formatstrict’ is not mandatory anymore. Changes value range of “dimension” parameter. Apple Advertising Identifier. ODIN and MACMD5 (not allowed from iOS 7). Added interstitial ads.
4.1.505/06/2014MORevised interstitials ad formats. Added Google advertising ID. Added “COPPA” parameter. Added MRAIDVER parameter.
5.003/19/2015NCIntroduced VAST video ads & Native Ads. (warning) Update: 2017-11-29: The non OpenRTB-conform NoAd response for VAST will not longer be supported. Vast/Video response will always be OpenRTB conform like in 5.0.1, even if requesting with apiver=500.
API 5.0.108/18/2015NCAdded OpenRTB-conform VAST No Ad Available Response.

API 5.0.2

11/17/2016BRAdded Outstream & Rewarded Video
API 6.0.0

  • New API endpoints
  • Click tracking support
  • Reworked response format


The SOMA API is the publisher interface used for communication with the Smaato Open Mobile Advertising infrastructure ("SOMA"). The SOMA API is designed to fulfill the needs of mobile publishers as well as mobile application and game developers.

The SOMA API can be requested by calling a specific URL with a query string of certain parameters. The SOMA server will respond via JSON.

Important New Features

(warning) The SOMA API 6.0.0 is not backward compatible.

Native, Richmedia, and Image are only supported by JSON. VAST is only supported by XML.

Click Tracking is now available and is mandatory to implement.

If you’re looking to 'ad-enable' a mobile application, please refer to our SDKs for information on all major platforms.

For a copy and paste client-side integration into your mobile site or app, check out our Ad Tag.

Adspace Sizes

The Adspace is the area you have designated for advertisements on your mobile website or application. For in-application advertising, the size of the Adspace is usually fixed. It is required that you adjust the size of your Adspace according to the internationally accepted ad formats defined by the Mobile Marketing Association (MMA).

Your Adspace must fit one of the following sizes:

320 x 480Fullscreen interstitial portrait mode
480 x 320Fullscreen interstitial landscape mode
768 x 1024

Fullscreen interstitial portrait mode - Tablet

1024 x 768Fullscreen interstitial lanscape mode - Tablet
320 x 50 (MMA XXLarge)The most common format and our recommendation

300 x 50 (MMA XLarge)

216 x 36 (MMA Large)

168 x 28 (MMA Medium)

120 x 20 (MMA Small)

Format Notes:

IAB ad formats

Smaato supports ads in the IAB medium rectangle (300 x 250), skyscraper (120 x 600) and leaderboard (728 x 90) format. The formats are designed to be used on tablets and on startup, interstitial or closing screens on smartphones.

Full Screen Ads

Smaato supports full screen ads that can be displayed for example as pre-roll, post-roll or interstitials.To request a full screen ad, use a full screen dimension parameter value (see parameter list below).

VAST Video Ads

VAST Video can be used for example for Pre-/Post-/Mid-Roll ads. They can ONLY be requested with “format=video”. VAST video ads supports only xml response format.

If you’re planning to use these formats, please contact us.

Native Ads

Smaato supports Native Ads. These are ads that can be shown the way you want and will look as if they are part of the app content. They can ONLY be requested with “format=native”.

Request URLs

The URL used for making requests to SOMA Server is:
For maximum monetization results we strongly advise you to use this URL.

To make requests in a secure SSL enabled environment the URL is:


Smaato is committed to protect privacy and data protection and strictly complies with applicable data protection laws. We require the client to inform the end user about the personable identifiable information it collects. Moreover, the client is obliged to give the end user the option to “Opt-out” from such action. If the end user chooses to “Opt-out” at any time, the client is required to promptly inform Smaato of an “Opt-out”.

Using the SOMA API

The SOMA API call consists of two separate http-requests. The first request can be established from a web server or from a mobile device directly. The response will contain the URL to download the image from the ad network’s server (or the ad text) and the click URL as well as URLs to impression tracker beacons for 3rd party validation. The second request, which downloads the banner image and impression tracker beacons (if applicable) must be made from the mobile device directly (!). Downloading the impression trackers is always required – even if the ad type is text!

Requesting advertisements from the SOMA API is done by calling the request URL (see below) with a set of parameters in the query string.

Figure 1: Ad Request Flow Chart

HTTP Header Forwarding

When using a Client<->Server<->SOMA architecture (the request to SOMA is not done directly by a mobile device) 

All http-headers that the publisher’s server receives from the mobile client need to be forwarded to SOMA.

Which headers are needed?

In general, we need to have ALL headers that the publisher's server receives from the communication with the mobile device forwarded. The only exceptions are custom headers that are set by your mobile application (for internal reasons).

Naming of the forwarded headers

We need to identify the forwarded headers and separate them from the headers from the communication with your server. For that reason, the headers need to be renamed. Please prefix all headers with “x-mh-” - even headers that have names starting with “x-”. The “x-” prefix has become a common way to indicate custom headers that are not standardized in any RFC (explanation on Microsoft TechNet).

Examples for original headers (your server received from the mobile device):

Accept-Charset: ISO-8859-1,UTF-8,US-ASCII,UTF-16BE,windows-1252,UTF-16LE,windows-1250
User-Agent: BlackBerry9000/ Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/111

Examples for the prefixed forwarded headers (your server forwards to the SOMA server):

x-mh-Accept-Charset: ISO-8859-1,UTF-8,US-ASCII,UTF-16BE,windows-1252,UTF-16LE,windows-1250
x-mh-User-Agent: BlackBerry9000/ Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/111

Impression and Click Tracking

Impression Trackers

Impression trackers, a.k.a. tracking pixels, impression beacons, view beacons, help to count the view of the advertiser’s ad via a third party and to double check ad server delivery.

An impression tracker is a transparent 1x1 GIF, which has to be requested by the mobile device directly after the ad is displayed.

Click tracking

For API integrations, Smaato relies on publishers to call what we call a 'click tracking' beacon. In every ad response (Image, Rich Media, Native and Video), Smaato can include zero (if the click tracking is made in a different way by using the creative itself for example) to multiple beacons under the clicktrackers object.

Click Trackers are manadatory to implement with SOMA API 6+

The click tracking beacons are included as an array of URLs inside of the "clicktrackers" object (see sample below). All Click Tracking beacons in the response must be called as soon as the end user clicks on the ad.

An ad response can also contain multiple click URLs which need to be called in case of a click event  (see the "clicktrackers": section in the response sample above). If you request ads using the API then you need to ensure that those click URLs are called from your client integration and not server side.

Response Example for IMG (Impression Tracker Excerpt)
       "impressiontrackers": [
       "clicktrackers": [

Responses may return multiple impression trackers; please note that all of them need to be handled in the same way.

For Impressiontrackers

Please make sure to place the impression trackers so that they're immediately called after the ad creative is rendered and not before!

This especially refers to the following case:

  • If an interstitial is being loaded in the background, the impressiontracker(s) should be called as soon as the creative is displayed, not when it’s been fully returned.

Please also respect the following in regards to the set-up of Click trackers and Impression trackers:

  • Modifying or redirecting the impressiontrackers or clicktracker URLs, placing the impression trackers or click trackers in a frame or layer or loading via JavaScript are not allowed.

AdSpaceID/PublisherID (parameters)

You can retrieve your IDs from the Smaato publisher portal.

Unique ID Parameters (IDFA, Google Advertising ID, Android ID)

Certain high-priced campaigns of our ad network partners require to anonymously identify users. The parameters above are used to transfer different types of these IDs.

For mobile application traffic at least one of these parameters is required.

Query String

It is important that you take care that the query string is separated and encoded correctly. Please refer to the encoding guidelines, e.g. RFC 3986 or Wikipedia if you are not sure.

A quick overview:

  • ? separates the query string from the rest of the URL.
  • & separates the field-value pairs (parameters).
  • The syntax for a parameter is [fieldname]=[value].
  • Only the following characters are allowed: 
    • Letters (A-Z and a-z)
    • Numbers (0-9)
    • The characters '.', '-', '~' and '_'
  • Space is encoded as +.
  • All other special characters are encoded with percent-encoding (e.g. %40 means @)
  • Use commas to separate multiple values of the same parameter (e.g. kws=hello,world,app)


General Parameters

adspaceYesAdSpaceID (assigned by Smaato). ID “0” can be used for unattended testing purpose.integer
pubYesPublisherID (assigned by Smaato). ID “0” can be used for unattended testing purpose.integer

The format of the ad to be returned (All formats will be returned in JSON except Video which will be in XML):

  • display: Image or rich media (strongly recommended!)
  • img: Any image format
  • richmedia: Rich media
  • video: Video Ads
  • native: Native Ads


Yes (‘no’ if the device is requesting directly or if you’re sending an x-forwarded-for header)The IP address of the requesting mobile device (this may differ from the request IP e.g. if a publisher’s web server is between the mobile device and SOMA).IP
refYes (‘no’ if the device is requesting directly or if you’re sending the correct referer header of the requesting webpage)Referer: The URL that identifies the address of the webpage where the ad request is coming
deviceYes (‘no’ if the device user agent is sent as a header)The user agent of the device's defaultstring

1 – MRAID 1.x
2 – MRAID 2.x



Yes (if format=video) 

Set to 2



videotypeYes (if format=video) 

Choose between:

  • instream-pre
  • instream-mid
  • instream-post
  • outstream
  • interstitial
  • rewarded

The desired dimension of ad to be returned:

  • xxlarge (recommended): this is the most common size (320 x 50)
  • medrect: IAB Medium Rectangle (300 x 250)
  • sky: IAB Skyscraper (120 x 600)
  • leader: IAB Leaderboard (728 x 90)
  • full_320x480: Interstitial ad for smartphones (portrait - switch dimensions for landscape)
  • full_640x960: Interstitial ad for tablets (portrait - switch dimensions for landscape)
  • full_640x1136: Interstitial ad for tablets (portrait - switch dimensions for landscape)
  • full_768x1024: Interstitial ad for tablets (portrait - switch dimensions for landscape)
  • full_800x1280: Interstitial ad for tablets (portrait - switch dimensions for landscape)
iosadidYes (for iOS applications)Apple’s Advertising Identifier. See herestring
iosadtrackingYes (for iOS applications)Apple’s advertisingTrackingEnabled Property. See here. (false = user has decided against tracking – this is the opposite way around as on Android)boolean
googleadidYes (for Android Applications)Google Android Advertising ID. See
googledntYes (for Android Applications)Android limit ad tracking preference. (true = user has decided against tracking – this is the opposite way around as on iOS)boolean
androididNoThe Android device’s Android ID (Settings.Secure.ANDROID_ID)string
wpidYes (for Windows Phone Applications)The Windows Phone Device IDstring513339592119231246

“0” will indicate that your content should not be treated as child-directed for purposes of COPPA.
“1” will indicate that your content should be treated as child-directed for purposes of COPPA.

integer 0 or 1

1 = subject to GDPR
0 = not subject to GDPR
value omited = unknown / unset (default)


0 or 1

gdpr_consentNoConsent string according to iAB's consent string format 1.1stringBOMT6szOMT6szAAABAENAAAAAAAAoAAA
carrierNoName of the current carrier.string
carriercodeNoMCC and MNC code of the current carrier. Format: carriercode={mcc}{mnc}. In the example the MCC is 234 and the MNC is 02.integer
heightNoHeight of the ad space. Recommended for in-application advertising.integer
widthNoWidth of the ad space. Recommended for applications.integer

Additional Targeting Parameters

The following parameters can be sent with the ad request in order to allow Smaato a more precise targeting of ads. Even though all of these parameters are optional it is strongly recommended to fill as many of them as possible. Better targetable inventory has a higher value to advertisers and is therefore very likely to be better monetized.
Important: Please inform your users what data you’re sending to third parties and allow them to opt-out. 

Parameter NameDescriptionRange Of ValuesExample
kwsTags (free text, case insensitive) describing the content.string: comma separated values
motorsport, news, cars
ageThe user’s age. 2-digit number. If only a range is available, use the mean average.integer
genderThe user's gender.m, fm
qsQuery String: A search term entered by the user within the mobile site.

string: comma separated values

coffee, san+francisco
Location: Information on the user’s location
gpsGPS coordinates of the user's location.string: Latitude and longitude in decimal degrees format, comma separated
regionThe region or state, the user is located in. (Abbreviated with two letter state code)string
CA (for California)
zipThe postal code of the user's location.string

Source of location data;


1 GPS/Location Services

2 IP Address

3 User provided (e.g., registration data)


If geotype=2, please provide the enrichment service you use:


1 ip2location

2 Neustar (Quova)

3 MaxMind

4 NetAcuity (Digital Element)

devicemodelThe device model. For iOS devices: The exact model.string



SOMA Video XML Response

Example (VAST Video): VAST Ads are supported by XML format only. For documentation on VAST XML response values, please refer to the IAB's VAST 2.0 Documentation.

<VAST version="2.0">
    <Ad id="223626102">
            <AdSystem version="2.0">Smaato</AdSystem>
            <AdTitle>Smaato Mobile Video</AdTitle>
            <Description>Press Play on Mobile Video Advertising</Description>
            <Survey />
                <Creative AdID="" sequence="1">
                            <Tracking event="start"><![CDATA[ ]]></Tracking>
                            <Tracking event="midpoint"><![CDATA[ ]]></Tracking>
                            <Tracking event="midpoint"><![CDATA[ ]]></Tracking>
                            <Tracking event="firstQuartile"><![CDATA[ ]]></Tracking>
                            <Tracking event="firstQuartile"><![CDATA[ ]]></Tracking>
                            <Tracking event="thirdQuartile"><![CDATA[ ]]></Tracking>
                            <Tracking event="thirdQuartile"><![CDATA[ ]]></Tracking>
                            <Tracking event="complete"><![CDATA[ ]]></Tracking>
                            <Tracking event="complete"><![CDATA[ ]]></Tracking>
                            <Tracking event="mute"><![CDATA[ ]]></Tracking>
                            <Tracking event="pause"><![CDATA[ ]]></Tracking>
                            <Tracking event="fullscreen"><![CDATA[ ]]></Tracking>
                            <Tracking event="fullscreen"><![CDATA[ ]]></Tracking>
                        <AdParameters />
                            <ClickThrough><![CDATA[ ]]></ClickThrough>
                            <ClickTracking id="DART"><![CDATA[ ]]></ClickTracking>
                            <ClickTracking id="ThirdParty"><![CDATA[ ]]></ClickTracking>
                            <MediaFile bitrate="457" delivery="progressive" height="720" id="1" type="video/mp4" width="1280"><![CDATA[
                <Creative AdID="" sequence="1">
                        <Companion height="250" width="300">
<a href="" target="_blank"><img src="" alt="" /></a>
                                <Tracking event="creativeView">https://myTrackingURL/secondCompanion</Tracking>

SOMA JSON Response

Below you will find examples JSON response examples for Image, Rich Media, and Native Ads. 

(warning) Please Note: Image, Rich Media, and Native Ads are supported by JSON format only 

Image Response type

imageObjectThe root object
image.imgObjectThe creative object
image.img.urlStringThe url of the image. Use this image to download and show the image creative in your app.
image.img.wStringThe width of the creative
image.img.hStringthe height of the creative
image.img.ctaurlStringThe creative click url. This url needs to be called when the user clicks on the ad.
image.impressiontrackersArrayAn array of URLs that contains all impression trackers. The impression trackers should be all called when the creative is visible on the screen.
image.clicktrackersArrayAn array of URLs that contains all click trackers. The click tracking URLs must be called as soon as the user clicks on the creative.
       "impressiontrackers": [
       "clicktrackers": [

Rich Media/JavaScript Response Type

richmediaObjectRoot object
richmedia.mediadataObjectCreative object
richmedia.mediadata.contentStringThe javascript code that needs to be rendered on the screen.
richmedia.mediadata..wStringCreative width
richmedia.mediadata.hStringCreative height
richmedia.impressiontrackersArrayAn array of URLs that contains all impression trackers. The impression trackers should be all called when the creative is visible on the screen.
richmedia.clicktrackersArrayAn array of URLs that contains all click trackers. The click tracking URLs must be called as soon as the user clicks on the creative.

   "richmedia": {
        "mediadata": {
            "content": "<THE CONTENT>",
            "w": "800",
            "h": "600"
        "impressiontrackers": [
       "clicktrackers": [

Native Ads Response Type

Please Note: In the native ad response, impression trackers are included in the "eventtrackers" array. The response format is the OpenRTB Dynamic Native Ads API Specification Version 1.2.

      "ver": "1.2",
         "url":"http: //",
         "clicktrackers" :[
               "text":"Learn about this awesome thing"
               "value":"My Brand"
               "value":"Learn all about this awesome story of someone using my product."

No Ad/ Error Response and Response Headers

VAST No Ad Available Response:

<VAST version="2.0"/>

The SOMA API excepts JSON request formats only  (except in the case of VAST which is handled in XML).

In case of no ad available or error the SOMA API will respond with following HTTP codes:





Currently no ad available

No ad is currently available matching the requesting parameter.


General Exception

Something went wrong on our side.

To know more about the kind of error, the SOMA API will add a description of the error in the response header X-SMT-MESSAGE


Unknown or blocked publisher

Returned when the publisher id is wrong or blocked internally.

Publisher Adspace mismatchWhen the publisher and adspace id don't belong to each other. Please check your ids in SPX and try again.
Unknown or blocked or deleted adspaceAdspace id blocked or removed
Invalid parameters for format VIDEOMissing parameters for the video ad request.
Invalid parameters for format NativeMissing parameters for the native ad request.
General ExceptionAll other errors

SOMA also returns the Ad Type in the response headers when an Ad is being returned. 

HeaderDescriptionPossible Values


Contains the ad response type to determine if the format is an image, rich media, native or video.

Img, Richmedia, Native, Video