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.211/17/2016BRAdded Outstream & Rewarded Video


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 API can be requested by calling a specific URL with a query string of certain parameters. The SOMA server will respond via HTML or XML.

Important Note:

If you’re looking to ad-enable mobile apps, please have a look at our SDKs for all major platforms.

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

If you’re looking for a server-based integration and you’re running a Java or PHP-based server environment, you may want to shorten the integration by using our PHP and JSP code snippets.

Adspace Sizes

The Adspace is the area you have designated for advertisements on your mobile web site or application. On mobile web sites, the size of this space is dynamic in most cases. SOMA uses device recognition to select the best fitting banner size.

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 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)

Please note: Larger formats are always preferable as they lead to higher click-through-rates and therefore higher revenues. See also: MMA Guidelines (PDF).

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).

*New: VAST Video Ads

VAST Video can be used for example for Pre-/Post-/Mid-Roll ads. They can ONLY be requested with “format=vast”. VAST Video ads can only be requested in combination with the response format “XML”.

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

*New: Native Ads*

Smaato supports native ads. Those 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”. If you’re planning to use these formats, please contact us

Request URLs

The URL used for making requests to SOMA Server 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 beacons for 3rd party validation. The second request, which downloads the banner image and beacons (if applicable) must be made from the mobile device directly (!). Downloading the beacons 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. The server responds with a HTML snippet to be pasted into your mobile site, or with an XML file. We recommend using the HTML response format.

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 your 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
X-Operamini-Phone-Ua: BlackBerry

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
x-mh-X-Operamini-Phone-Ua: BlackBerry


Like the online advertising market did several years ago, the mobile advertising market starts demanding trusted parties to validate traffic, data and performance.

Beacons, or so-called tracking pixels, help to count the view of the advertiser’s ad via a third party and to double check ad server delivery.

A beacon is a transparent 1x1 GIF, which has to be requested by the mobile device directly after the banner image or the text ad, is displayed.

How to handle beacons correctly:

The beacon portion of the response starts with the opening tag <beacons>, and closes with </beacons>.

Within this portion, each beacon will accordingly start with <beacon>, and end with </beacon>.

Response Example (Beacon Excerpt)

Responses may return multiple beacons; please note that all of them need to be handled.

Please make sure to set up the beacon call so that it is immediately called after the ad creative is displayed, but not before that!

This especially refers to e.g. the following case: if an interstitial is being loaded in the background, the beacon(s) should be called as soon as the creative is displayed, not as soon as it’s fully been returned.

Please also respect the following:

  • Modifying or redirecting the beacon URL, loading the beacon via JavaScript or placing the beacon in a frame or layer are not allowed
  • In the HTML code, the beacon must be placed right after the ad

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).
  • ; separates the J-Session parameter
  • 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




The version of the API you’re using (version of this document).

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


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
dividyes (for mobile web)

Mobile Web only: The ID of the div (or equally suitable HTML element) that you're using to serve the ad. This needs to be formatted in the following way: smt-[AdspaceID]

Please note: If you fail to do this, ad display may not work.

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




The requested native ad component names separated by comma. If not set, at least a title and a click through url will be included in the ad response. 


Comma separated values. 

title, txt, icon, image, ctatext 


Yes (if format=video) 

Set to 2 or 3 or 4


2 or 3 or 4


Yes (if format=native) 

Set to 1 


videotypeYes (if format=video) 

Choose between:

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

The format of the ad to be returned:

  • all: Image or rich media (strongly recommended!)
  • img: Any image format
  • richmedia: Rich media
  • video: Video Ads
    (Note: “response” must be “XML”)
  • native: Native Ads
    (Note: “response” must be “XML” & API integrations need to be capable calling multiple click URLs (see examples below)) 
formatstrictnoDefault: false. When the format parameter is handled as “strict” only the desired format will be delivered. If it’s not strict, an alternative format might be delivered, if the desired format is not available.boolean

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)

Default: false.
When the dimension parameter is handled as “strict” only the desired dimension will be delivered. If it’s not strict, an alternative dimension might be delivered, if the desired format is not available.

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
bbidyes (for BlackBerry Applications)The BlackBerry Device IDstringe3365064be00b474622467f06493a2d282a464ad
wpidyes (for Windows Phone Applications)The Windows Phone Device IDstring513339592119231246
responseyesDesired format of the response. xml, html or json. (must be XML for Video).string
coppayes (traffic from the US)

“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.

0 or 1
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
sessionnoA MD5 hash generated at the start of every session and used throughout the whole session. We recommend hashing the device’s hardware ID and the time of session start.mD5

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.string
zipThe postal code of the user's location.string
devicemodelThe device model. For iOS devices: The exact model.string
devicemakeThe device manufacturer.string
areacodeThe current location area code (LAC).string

SOMA HTML Response

The server response will include one or both of the following header-information:

1. “SomaError”

This header will be sent if any error occurs. If no error occurred, this header will not be sent.

2. “SomaUserID”

If this header is sent within the response, the value MUST be used for ALL future requests of this specific user. Example: SomaUserID: 900

The HTML code, depending on the ad-format, looks like:

<a href="[link to the landing page]">
<img src="[link to the image]" ... />
<img src="[link to the beacon]" width="1" height="1" border="0" />

Example (image):

	<a rel="nofollow" href=";jsessionid=3DF931BBBDC62F7029057AD9C00037A8.soma-i-b1b9a84a">
		<img src=";jsessionid=3DF931BBBDC62F7029057AD9C00037A8.soma-i-b1b9a84a" border="0" alt="" width="320" height="48"/>
		<img border="0" src=";jsessionid=3DF931BBBDC62F7029057AD9C00037A8.soma-i-b1b9a84a" alt=""/>

Example (Richmedia /JavaScript):

<script type=’text/javascript’>
// some javascript code
</script> <noscript>Advertisement</noscript>
<img border="0" src=";jsessionid=88F36D0C333AF30C6A3EEF0ECB8592E7.soma-i-dc746830" alt="">

Example for No Ad Available:

The header will contain the SomaError code 42; Currently no ad available.


SOMA XML Response

Example (Image):

<response xmlns="" xmlns:xsi="" xsi:schemaLocation="">
<ad id="0" type="IMG" width="320" height="50">
<valid start="0" end="0" max="1"/>
<action target=""acc="server"/>

Example (VAST Video):

<VAST version="2.0">
<Ad id="223626102">
<AdSystem version="2.0">Smaato</AdSystem> <AdTitle>In-Stream Video</AdTitle>
<Description>A test creative with a description.</Description> <Survey/>
<Creative sequence="1" AdID="">
<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>
<ClickThrough><![CDATA[ ]]></ClickThrough>
<ClickTracking id="DART"><![CDATA[]]></ClickTracking>
<ClickTracking id="ThirdParty"><![CDATA[]]></ClickTracking>
<MediaFile id="1" delivery="streaming" type="video/mp4" bitrate="457" width="300" height="225"><![CDATA[]]></MediaFile>
<Creative sequence="1" AdID="">
<CompanionAds><Companion height="50" width="320" id="555750">
<HTMLResource><![CDATA[<img src="" height="50" width="320">]]></HTMLResource>
</Companion></CompanionAds> </Creative>

Example (Rich Media/JavaScript):

<response xmlns="" xmlns:xsi="" xsi:schemaLocation="">
<sessionid>2D085D2024BB001344ABE19E72DEE244.soma-i-b1b9a84a</sessionid> <status>success</status>
<ownid>358240057024713</ownid> </user>
<ad id="0" type="RICHMEDIA"> <log-id/>
<valid start="0" end="0" max="1"/> <mediadata>
<script src=\"mraid.js\"><\/script>\r\n<div class=\"celtra-ad-v3\">\r\n
style=\"display: none\" onerror=\"\r\n (function(img) {\r\n {\'clickUrl\':\'\',\'clickEvent\':\'advertiser\',\'externalAdServer\':\'Custom\'};\r\n var req = document.createElement(\'script\');\r\n = params.scriptId = \'celtra-script-\' + (window.celtraScriptIndex = (window.celtraScriptIndex||0)+1);\r\n params.clientTimestamp = new Date\/1000;\r\n var src = (window.location.protocol == \'https:\' ? \'https\' : \'http\') + \':\/\/\/9d69ec31\/mraid-ad.js?\';\r\n for (var k in params) {\r\n
+ encodeURIComponent(k) + \'=\' + encodeURIComponent(params[k]);\r\n }\r\n
src;\r\n img.parentNode.insertBefore(req, img.nextSibling);\r\n })(this);\r\n
<action target="" type=""/>

Example (Native Ads):

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="" xmlns:xsi="" xsi:schemaLocation="">
      <ownid />
      <ad id="0" type="NATIVE">
         <log-id />
         <valid start="0" end="0" max="1" />
            <adtext>The Leading Global Mobile RTB Ad Exchange andi SSP</adtext>
               <icon width="80" height="80">;jsessionid=83E48A90C2565475700B60C3B92E57E7.soma-i-99a8e47d?</icon>
               <image width="1200" height="627">;jsessionid=83E48A90C2565475700B60C3B92E57E7.soma-i-99a8e47d?</image>
            <ctatext>Read more</ctatext>
            <beacons />

Example (Native Ads with multiple Click URLs):

A native ads response can also contain multiple clicks URLs which need to be called in case of a click event (see the <clicktrackingbeacon> section in the response below). Please note that the <clicktrackingbeacon> tag is optional.
If you request native ads using using the API then you need to ensure that those click URLs are called from your client integration and not server side.

    xmlns:xsi="" xsi:schemaLocation="">
        <ownid />
        <ad id="0" type="NATIVE">
            <log-id />
            <valid start="0" end="0" max="1" />
                <adtext>The Leading Global Mobile RTB Ad Exchange and SSP</adtext>
                    <icon width="75" height="75"></icon>
                    <image width="1200" height="627"></image>
                <ctatext>Read more</ctatext>

SOMA XML Response Value Description

status: The status of the response. Possible values are “success” or “error” (see error codes below).

user: Information about the user:

  • id: Deprecated
  • ownid (optional): The unique hardware ID of the device sent during the request.

ads: The meta data of the ads returned (usually one ad)

  • id: The unique id of the ad.
  • type: The type of the ad. Possible values are IMG for banner ads, TXT for text ads, VIDEO for video ads or RICHMEDIA for richmedia (JavaScript / HTML5) ads. Depending on the campaign, the IMG type may be more detailed (GIF,JPEG or PNG).
  • width (optional): The width of the image ad.
  • height (optional): The height of the image ad.
  • log-id: The unique id generated by the ad-server to store the appropriate tracking information.
  • valid: The validity period of the ad.
  • start: Start-date from when the ad can be shown (in milliseconds since 01.01.1970).
  • end: End date until the ad can be shown (in milliseconds since 01.01.1970).
  • max: Describes how often the ad can be shown (usually 1).

link: The link to the ad itself. Empty if it is a text-ad or video ad.

mediafiles: (Video Ads only) The meta data of the video ads returned (usually one file)

mediafile: The URI of the video ad file.

  • delivery: The delivery scheme (normally “progressive”)
  • bitrate: The bitrate of the video.
  • type: The MIME-Type of the video.

mediadata: (Rich Media only): The HTML/JavaScript code of the ad.

action: Describes the action(s) associated to the ad.

  • type …of the action. Possible values can be LINK (more to follow).
  • target URI, e.g. URL of the landing page or a WTAI call.
  • acc …states, where the accounting takes place. Currently Server is supported.

adtext (optional for image ads, n/a for video ads): Main advertising text.

adtextdescription: Additional (descriptive) lines of ad text (up to 3 lines to be displayed below the main ad text).

descriptionline: Additional line of ad text.

snast: native ad tag that will contain the creative items

adtitle: The ad title, 

adtext: The ad text.

iconimage: icon image tag that will contain the icons (usually one)

icon: The icon URL (80 x 80 px recommended)

mainimage: The main image tag that contains the images (usually one)

image: The image URL (1200 x 627 px recommended)

starrating: a float e.g. 4.5, which is usually served when the creative is related to an app advertisement.

ctatext: The text that should be used for the click to action button e.g. "Install" or "Learn more"

clickurl: click url that should be used to redirect the user when he clicks on the ad

beacons: Tracking pixels that have to be requested when the ad is displayed.

beacon: The URL to a beacon.

For documentation on VAST XML response values, please refer to the IAB's VAST 2.0 Documentation.

XML Error Response

If an error occurs while processing the request or no ad can be delivered an error will be sent.

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns="" xmlns:xsi="" xsi:schemaLocation="">
      <desc>Currently no ad available</desc>

Please note: From API Version 5.0.1 on, VAST No Ad Available Responses are returned according to OpenRTB specifications:

VAST No Ad Available Response:

<VAST version="2.0"/>

Possible request error codes (for XML and HTML responses)





Currently no ad available

No ad is currently available matching the requesting parameter. The following descriptions are possible (between <desc> and </desc>:

-        Currently no ad available The standard response.

-        BOT-Request: (User-Agent: bot.txt( The request has been identified to be a bot request.

-        Invalid IP-Request: ( The DEVIP parameter was set to an invalid IP address (e.g. private IPs)


Missing parameters inside request

One or more of the mandatory parameters was not sent.



Different error descriptions. Please provide the description after receiving this error if you cannot fix it on your own.


General Exception

Something went wrong on our side.

SOMA JSON Response

We also provide responses in JSON (please note: as HTML, JSON doesn't work for video!) - if you're interested in that, just set the response parameter to json. This is an example response: