Click here to expand Version History!

Version History

VersionDateAuthorComment
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.
3.1.2.04/23/2009MOAdded section that describes the beacon support. Changes in the header forwarding section. Layout changes.
3.1.3.06/05/2009MOAdded development and production server URLs. 
3.1.4.07/02/2009MOExtended the http header forwarding section. Added description to error code 42. 
3.1.5.09/04/2009MOAdded 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. 
3.1.7.02/16/2010MOAdded parameters for analytics. Added medium rectangle format. Minor changes.
3.1.8.04/16/2010MONew URLs are smaato.net 
3.3.0.04/27/2011MORestructuring of the parameter section. New targeting parameters. Minor maintenance changes und updates. Section “OwnId” updated. Added privacy section. Video Ads. 
4.0.0.06/09/2011MOAdded Rich Media Ad Format. Important: Enhanced usage of parameter “format”. Added new parameters “dimensions” and “formatstrict”. 
4.0.1.10/26/2011MOMinor changes. Added multiline text ads (see XML response description). 
4.1.2.05/22/2012MOMajor 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.
4.1.3.09/28/2012MOAdded Apple Advertising Identifier.
4.1.4.07/01/2012MORemoved 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

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


Introduction

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:


SIZEDESCRIPTION
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: http://soma.smaato.net/oapi/v6/ad
For maximum monetization results we strongly advise you to use this URL.

To make requests in a secure SSL enabled environment the URL is: https://soma.smaato.net/oapi/v6/ad

Privacy

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

X-Wap-Profile: http://www.blackberry.net/go/mobile/profiles/uaprof/9000_umts/4.6.0.rdf
Accept-Charset: ISO-8859-1,UTF-8,US-ASCII,UTF-16BE,windows-1252,UTF-16LE,windows-1250
User-Agent: BlackBerry9000/4.6.0.162 Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/111
X-Forwarded-For: 203.177.91.193, 62.159.30.165, 67.69.254.254


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

x-mh-X-Wap-Profile: http://www.blackberry.net/go/mobile/profiles/uaprof/9000_umts/4.6.0.rdf
x-mh-Accept-Charset: ISO-8859-1,UTF-8,US-ASCII,UTF-16BE,windows-1252,UTF-16LE,windows-1250
x-mh-User-Agent: BlackBerry9000/4.6.0.162 Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/111
x-mh-X-Forwarded-For: 203.177.91.193, 62.159.30.165, 67.69.254.254

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)
{
   "image":{
      "img":{
         "url":"http://some.creative.url",
         "w":"320",
         "h":"50",
         "ctaurl":"http://landing.page.url/buyMe"
       },      
       "impressiontrackers": [
            "http://www.mytracker.com/impressiontracker01",
            "http://www.mytracker.com/impressiontracker02"
       ],
       "clicktrackers": [
            "http://www.mytracker.com/clicktracker01",
            "http://www.mytracker.com/clicktracker02"
      ]
   }
}

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)

Example:
http://soma.smaato.net/oapi/v6/ad?adspace=0&pub=0&devip=123.45.67.89&device=Nokia1680c-2%2F2.0+%2805.61%29+Profile%2FMIDP-2.1+Configuration%2FCLDC-1.1&format=richmedia

General Parameters

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

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
string
img

devip

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
123.45.678.90
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 from.stringhttp%3A%2F%2Fwww.example.com
deviceYes (‘no’ if the device user agent is sent as a header)The user agent of the device's defaultstring
Mozilla%2F5.0%20(Linux%3B%2
0U%3B%20Android%202.2.1%3B%
20en-us%3B%20Nexus%20One%20
Build%2FFRG83)
%20AppleWebKit%2F533.1%20(K
HTML%2C%20like%20Gecko)%20V
ersion%2F4.0%20Mobile%20Saf
ari%2F533.1
mraidver

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

integer
2

vastver 

Yes (if format=video) 

Set to 2

integer 

2

videotypeYes (if format=video) 

Choose between:

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

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)
string
xxlarge
iosadidYes (for iOS applications)Apple’s Advertising Identifier. See herestring
1D76F5D1-1983-47C8-B18D-119D52E4597A
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
true
googleadidYes (for Android Applications)Google Android Advertising ID. See http://bit.ly/MBMTTJstring
40d9e394-740a-4225-83f1-766a04154b83
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
true
androididNoThe Android device’s Android ID (Settings.Secure.ANDROID_ID)string
9774d56d682e549c
wpidYes (for Windows Phone Applications)The Windows Phone Device IDstring513339592119231246
coppaYes

“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
0
gdprNo

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

integer

0 or 1

0
gdpr_consentNoConsent string according to iAB's consent string format 1.1stringBOMT6szOMT6szAAABAENAAAAAAAAoAAA
carrierNoName of the current carrier.string
o2uk
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
23402
heightNoHeight of the ad space. Recommended for in-application advertising.integer
36
widthNoWidth of the ad space. Recommended for applications.integer
36

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
Content
kwsTags (free text, case insensitive) describing the content.string: comma separated values
motorsport, news, cars
User
ageThe user’s age. 2-digit number. If only a range is available, use the mean average.integer
30
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
37.530676,-122.262447
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
94402
geotype

Source of location data;

integer

1 GPS/Location Services

2 IP Address

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

1
ipservice

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

integer

1 ip2location

2 Neustar (Quova)

3 MaxMind

4 NetAcuity (Digital Element)

3
Device
devicemodelThe device model. For iOS devices: The exact model.string
iPhone3,1

Responses

Endpoint

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">
        <InLine>
            <AdSystem version="2.0">Smaato</AdSystem>
            <AdTitle>Smaato Mobile Video</AdTitle>
            <Description>Press Play on Mobile Video Advertising</Description>
            <Survey />
            <Impression><![CDATA[
http://ets-eu-west-1.smaato.net/v1/view?sessionId=5124d8ff-eda5-4da0-81ac-0987886b0d8d&adSourceId=85979a9c-7aee-48c2-8cfb-9eb4e25a6fca&originalRequestTime=1523542253549&expires=1523543153549&winurl=lR01FIl5HBPqUGcVDsFK1V8COQwE30Wo7CYapFW6sDycVCRT4jZ-CIsQijfuors1wvCEsqAKp7V1J2_oqWBzU0S5DtP1vvh0sxudsDoT4melTtBi8Po66GA4FZcUYn5IojsAapnNcFZS0-Bj_RdzFLL9wwIxGwlZAGR2qoAVj9Kjv4fBQAdRMKrItcEad96WWwHNpYOm_Nr9Y6asqNh1-vMYD4e9wA6aew1Fx-BsI-Xl9BuWpwvhDS22Eu-Hqz_MmStVI_gYE8emjfe6lIhRmw%3D%3D%7C8CV4DG05IMa2TbSAPnH9rQ%3D%3D
]]></Impression>
            <Creatives>
                <Creative AdID="" sequence="1">
                    <Linear>
                        <Duration>00:00:15</Duration>
                        <TrackingEvents>
                            <Tracking event="start"><![CDATA[ https://soma.smaato.net/videoStart ]]></Tracking>
                            <Tracking event="midpoint"><![CDATA[ https://soma.smaato.net/midPoint ]]></Tracking>
                            <Tracking event="midpoint"><![CDATA[ https://soma.smaato.net/midPoint2 ]]></Tracking>
                            <Tracking event="firstQuartile"><![CDATA[ https://soma.smaato.net/firstQuartile ]]></Tracking>
                            <Tracking event="firstQuartile"><![CDATA[ https://soma.smaato.net/firstQuartile2 ]]></Tracking>
                            <Tracking event="thirdQuartile"><![CDATA[ https://soma.smaato.net/thirdQuartile ]]></Tracking>
                            <Tracking event="thirdQuartile"><![CDATA[ https://soma.smaato.net/thirdQuartile ]]></Tracking>
                            <Tracking event="complete"><![CDATA[ https://soma.smaato.net/complete ]]></Tracking>
                            <Tracking event="complete"><![CDATA[ https://soma.smaato.net/complete2 ]]></Tracking>
                            <Tracking event="mute"><![CDATA[ https://soma.smaato.net/mute ]]></Tracking>
                            <Tracking event="pause"><![CDATA[ https://soma.smaato.net/pause ]]></Tracking>
                            <Tracking event="fullscreen"><![CDATA[ https://soma.smaato.net/fullscreen ]]></Tracking>
                            <Tracking event="fullscreen"><![CDATA[ https://soma.smaato.net/fullscreen2 ]]></Tracking>
                        </TrackingEvents>
                        <AdParameters />
                        <VideoClicks>
                            <ClickThrough><![CDATA[ https://www.smaato.com ]]></ClickThrough>
                            <ClickTracking id="DART"><![CDATA[ https://soma.smaato.net/clickTracking ]]></ClickTracking>
                            <ClickTracking id="ThirdParty"><![CDATA[ https://soma.smaato.net/clickTracking2 ]]></ClickTracking>
                            <ClickTracking><![CDATA[
http://ets-eu-west-1.smaato.net/v1/click?sessionId=5124d8ff-eda5-4da0-81ac-0987886b0d8d&adSourceId=85979a9c-7aee-48c2-8cfb-9eb4e25a6fca&originalRequestTime=1523542253549
]]></ClickTracking>
                        </VideoClicks>
                        <MediaFiles>
                            <MediaFile bitrate="457" delivery="progressive" height="720" id="1" type="video/mp4" width="1280"><![CDATA[
https://demofiles.smaato.com/creatives/assets/video/Outstream%20Demo%20Asset%20Mockup.mp4?test=true
]]></MediaFile>
                        </MediaFiles>
                    </Linear>
                </Creative>
                <Creative AdID="" sequence="1">
                    <CompanionAds>
                        <Companion height="250" width="300">
                            <HTMLResource><![CDATA[
<a href="https://www.smaato.com/resources/adformats/#section1" target="_blank"><img src="https://smt-demofiles.s3.amazonaws.com/creatives/assets/images/600x500.png" alt="" /></a>
]]></HTMLResource>
                            <TrackingEvents>
                                <Tracking event="creativeView">https://myTrackingURL/secondCompanion</Tracking>
                            </TrackingEvents>
                            <CompanionClickTracking><![CDATA[
http://vet.smaatolabs.net/companionClickTracking?sessionId=5124d8ff-eda5-4da0-81ac-0987886b0d8d&adSourceId=85979a9c-7aee-48c2-8cfb-9eb4e25a6fca&originalRequestTime=1523542253549
]]></CompanionClickTracking>
                        </Companion>
                    </CompanionAds>
                </Creative>
            </Creatives>
        </InLine>
    </Ad>
</VAST>

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


AttributeTypeDescription
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.
{
   "image":{
      "img":{
         "url":"http://some.creative.url",
         "w":"320",
         "h":"50",
         "ctaurl":"http://landing.page.url/buyMe"
       },      
       "impressiontrackers": [
            "http://www.mytracker.com/impressiontracker01",
            "http://www.mytracker.com/impressiontracker02"
       ],
       "clicktrackers": [
            "http://www.mytracker.com/clicktracker01",
            "http://www.mytracker.com/clicktracker02"
      ]
   }
}

Rich Media/JavaScript Response Type

AttributeTypeDescription
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": [
            "http://www.mytracker.com/impressiontracker01",
            "http://www.mytracker.com/impressiontracker02"
       ],
       "clicktrackers": [
            "http://www.mytracker.com/clicktracker01",
            "http://www.mytracker.com/clicktracker02"
      	]
    }
}

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.

{ 
   "native":{ 
      "ver": "1.2",
      "link":{ 
         "url":"http: //i.am.a/URL",
         "clicktrackers" :[
            "http://www.mytracker.com/clicktracker01",
            "http://www.mytracker.com/clicktracker02"
        ]
      },
      "assets":[ 
         { 
            "id":123,
            "required":1,
            "title":{ 
               "text":"Learn about this awesome thing"
            }
         },
         { 
            "id":124,
            "required":1,
            "img":{ 
               "url":"http://www.myads.com/thumbnail1.png"
            }
         },
         { 
            "id":128,
            "required":1,
            "img":{ 
               "url":"http://www.myads.com/largethumb1.png",
               "w":"800",
               "h":"600"
            }
         },
         { 
            "id":126,
            "required":1,
            "data":{ 
               "value":"My Brand"
            }
         },
         { 
            "id":127,
            "required":1,
            "data":{ 
               "value":"Learn all about this awesome story of someone using my product."
            }
         }
      ],
      "eventtrackers":[ 
         { 
            "event":1,
            "method":1,
            "url":"http://www.mytracker.com/impressiontracker01"
         },
         { 
            "event":1,
            "method":1,
            "url":"http://www.mytracker.com/impressiontracker02"
         }
      ]
   }
}

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:

HTTP Code

Description

Comment

204

Currently no ad available

No ad is currently available matching the requesting parameter.

400

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

MessageDescription

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

X-SMT-ADTYPE

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

Img, Richmedia, Native, Video