Follow

Server-to-Server JSON API Ad Request

This document guides you through the integration of the StartApp server-to-server API.

Once integrated, the API enables partners to retrieve ads and embed them into their applications and mobile websites. Examples of the various ad request types are included, together with the response that will be received.

 Important notes

  1. The API uses HTTP GET method. The response parameters are returned in a JSON format in the HTTP body
  2. Ad request parameters MUST be URL encoded
  3. Access to StartApp’s server is restricted, partnerId and token will be provided upon integration request
  4. StartApp’s ad server optimizes the ads it returns according to the parameters in the request and other offline dimensions. Therefore, it is not recommended to store or cache the ads.

 If you have any questions, please contact us via support@startapp.com.

Resource Details

URL: http://s2s.startappnetwork.com/s2s/1.3/ads
HTTP Method: GET
API Version:
1.3
Response Format:
JSON

Mandatory Request Parameters

 Recommended Request Parameters

Optional Request Parameters

Response Parameters

Example for Native ad

Request

http://s2s.startappnetwork.com/s2s/1.3/ads?partner=856974125&token=778645132&segId=65437653&pub=12345&prod=com.foobar.app&dip=205.232.37.108&ua=Mozilla%2F5.0%20(Linux%3B%20Android%204.1.1%3B%20SGH-I747%20Build%2FJRO03C)%20AppleWebKit%2F535.19%20(KHTML%2C%20like%20Gecko)%20Chrome%2F18.0.1025.166%20Mobile%20Safari%2F535.19&adw=100&adh=100&adType=2&os=0&osVer=4.1&isp=42501&adsNum=1&reqId=1245

Response

{

responseCode: 200,

responseMessage: "OK",

reqId: "1245",

ads:

[

{

clickUrl: "http://www.startappexchange.com/tracking/adClick?d=IAAAAAAgAAA6X14UG0lNXFtfCkgYQ0ZSX0AEREdIVgYUHF1FWVpfW1UaFUJYRkVCQk1UQFBRSEhJWFtaWFNIQUBZR0FRSFNQU1dATEBFSl5eVl1MRU1WRkVTRVNUX15ETERHXllbWEZIQUkyMyQ%2BSENWTVpFREJEXEFcWFdXQENPQ0RZU0FWUzAzKS9FXllYXUZORklMRlpRU0FRUzAzKS9DX11aW0ZIRkkzOzcpLyQgNjdRSEZJGgYADAkcUEVWT0VCQUlYDQwfVxYbBg0PGUsYAwRCQERcIzctQypFTUdXW11TWlNaQUdcQ0ZSREVGXFdPGh8ZRwkBBAcYAVoAAgRCQkdYXU1GWkJMVCYgODE4PzhCQURcJSNGXVJPKzk3ITA6Lj0tUEdTTzUxOS8rLzc7LzVXWlhTAggYFBE%2BBhEMABwEGgZRSklJJCAsIik8UEBRTzEXFQIcAQ0XWkRHVAkPBxYcUEBVT0NCREVYXkBGT00kJCIiKAQNUEBWTzcuICkkOzc9WkRMVFpbWEtJUEBYTxIDSUlQWlITVBFEW1xDXwBNRFlZFxICXRFUXlZDSUAXD1lXX0ZMQ0kgPDAzPzkhTVZBRDc1JCoxODErMiAkNS1CRURYOCJRTEZJWF9eW0tJUEFWT0VRQEBLXkBESU0jICknSFNLTkVTRkFCRkNYXUBETE0nWzxNXVNEJB0PFgcVAhUEA0MwDAMdBwodGEZPRElRXEdRQUhXWlBESEBMXFdXWlJaRERcERsMXh0EDQsbFxUOBgELRQIWBFdWQ0kxNTcsTlJAWkdGVAkPBxYcUENSTxwEXTkpTVRGREZNSlhWVlRJQ1dWS0lQQEBGVlVPPTknKC0iLiFaS0FcFBUNAxVGVlRPSV5HWV5WWVFKRUVRSkFZSUFSTVtKRF1FR19NU1xEXkVPQlc%3D&ru=http%3A%2F%2Fcontrol.kochava.com%2Fv1%2Fcpi%2Fclick%3Fcampaign_id%3Dkogameofwarfireage1541528ae4547febba5ed6470c38b9%26network_id%3D300%26click_id%3D-5lUGqAjTkeO_hBRAM9pQQ%26site_id%3D65437653%26creative_id%3DRich%26device_id_type%3Dadid%26append_app_conv_trk_params%3D1&index=0",

campId: "SAP_17666",

title: "Game of War - Fire Age",

desc: "“I found Game of War – Fire Age more engaging than its closest analogue Clash of Clans” -- NY TimesJoin the ULTIMATE Battle for Domination of the Kingdom! PLAY FOR FREE in the most addicting & interactive Action Strategy MMO GAME!! Join millions of Online Players from around the world, BE PART ...",

img: "http://images.startappservice.com/image/fetch/f_auto,q_80,w_100,h_100/http%3A%2F%2Flh3.ggpht.com%2Fg3S82b8rLnIN-uG0ffQPJQCmqsWQ1Im9kQff1BJArot77A78Fam7PcWLrnXSdGyRgTs",

inPos: "1",

rate: 3.9726002,

installs: "10,000,000 - 50,000,000",

isApp: true,

impUrl: "http://www.trackimpression.com/tracking/adImpression?d=IAAAAAAgAAA6X14UG0lNXFtfCkgYQ0ZSX0AEREdIVgYUHF1FWVpfW1UaFUJYRkVCQk1UQFBRSEhJWFtaWFNIQUBZR0FRSFNQU1dATEBFSl5eVl1MRU1WRkVTRVNUX15ETERHXllbWEZIQUkyMyQ%2BSENWTVpFREJEXEFcWFdXQENPQ0RZU0FWUzAzKS9FXllYXUZORklMRlpRU0FRUzAzKS9DX11aW0ZIRkkzOzcpLyQgNjdRSEZJGgYADAkcUEVWT0VCQUlYDQwfVxYbBg0PGUsYAwRCQERcIzctQypFTUdXW11TWlNaQUdcQ0ZSREVGXFdPGh8ZRwkBBAcYAVoAAgRCQkdYXU1GWkJMVCYgODE4PzhCQURcJSNGXVJPKzk3ITA6Lj0tUEdTTzUxOS8rLzc7LzVXWlhTAggYFBE%2BBhEMABwEGgZRSklJJCAsIik8UEBRTzEXFQIcAQ0XWkRHVAkPBxYcUEBVT0NCREVYXkBGT00kJCIiKAQNUEBWTzcuICkkOzc9WkRMVFpbWEtJUEBYTxIDSUlQWlITVBFEW1xDXwBNRFlZFxICXRFUXlZDSUAXD1lXX0ZMQ0kgPDAzPzkhTVZBRDc1JCoxODErMiAkNS1CRURYOCJRTEZJWF9eW0tJUEFWT0VRQEBLXkBESU0jICknSFNLTkVTRkFCRkNYXUBETE0nWzxNXVNEJB0PFgcVAhUEA0MwDAMdBwodGEZPRElRXEdRQUhXWlBESEBMXFdXWlJaRERcERsMXh0EDQsbFxUOBgELRQIWBFdWQ0kxNTcsTlJAWkdGVAkPBxYcUENSTxwEXTkpTVRGREZNSlhWVlRJQ1dWS0lQQEBGVlVPPTknKC0iLiFaS0FcFBUNAxVGVlRPSV5HWV5WWVFKRUVRSkFZSUFSTVtKRF1FR19NU1xEXkVPQlc%3D",

maturity: 2,

advertiser: "Machine Zone, Inc.",

pck: "com.machinezone.gow",

cat: "GAME_STRATEGY"

}

]

}


RequestExample For 1200X628 Native ad

http://s2s.startappnetwork.com/s2s/1.3/ads?partner=856974125&token=778645132&segId=65437653&pub=12345&prod=com.foobar.app&dip=205.232.37.108&ua=Mozilla%2F5.0%20(Linux%3B%20Android%204.1.1%3B%20SGH-I747%20Build%2FJRO03C)%20AppleWebKit%2F535.19%20(KHTML%2C%20like%20Gecko)%20Chrome%2F18.0.1025.166%20Mobile%20Safari%2F535.19&osVer=4.1&isp=42501&adsNum=1&reqId=1245&adw=1200&adh=628&adType=2&os=0&sizeFlag=true

Response

{

responseCode: 200,

responseMessage: "OK",

reqId: "1245",

ads: [

{

clickUrl: "http://www.startappexchange.com/tracking/adClick?d=IAAAAAAgAAA6X15DSUJEUVZdDUgdRUECX0AERkhIVlQQGF1MDQlYXVcfRRcDS0VCQk1UQFBRSEhJWFtaWFNIRkBZRkFXSVNQU1dATEBFSl5eVl1MRU1WRkVTRVNUX15ETERHXllbWEZIQUkyMyQ%2BRElXWFtRQEdJW19bRVdKQVpSRVpQQEhGX1BPKjEkNl5cX11ORldWR0lMRF5VTVJGRCM1OTBZWVNOR0FCQ0FcIjkmJjwmPCggSl5YVhYQHRMNF1dQR01UTVJLRBMbBEEIBAobEgZPEwQRU0JVUzA1MV09XltZSFdLTkVXUUZSTUFXXVdHWkJAVAwBBksfHBsDEwZPEQAVTVFFREFaXkxcU1gwPSc1MzgtU0NVUzYhWkNFVD0nKC0mJzE5JldSQk0kPiotNzEgIDkrSFZOThIAEREDHx8OMQUXHBRXWlZTJio7OjgkUUBRTTUTCxELFh4RSltdVgMYHwcEUUBVTUdGWlZPSVNAX1I%2BJig1MBUVUUBWTTMqPjozLCQ7SltWVlxKR1pRUUBYTUFVXFNKQEMSRAtYXgZURxFXSllZRxJVQwJKHRZCX10IXQYbSldUQkkgPjQ3ISo2WkVHVCgvJiAmIyE7KDgkU0VRUzUzWkVCVF5eW1VXQ1dURUlQQEBVQFNRT0BJPiYoIkZPQUlQQEBUU0ZWU1BRT0VJOl09SFNPTiMIHBASBAIADw5SOwUHAAELGBZaRUNcQlpQSEBVXFRASkFBXlteXl1MQFdWQkkPFQRLHgYTEhcVBAodRQQUCldWQ0kxNTcsTlBRTkJJDw4CGABaREdcGhFMOTxGWVdPQUVNWVZWWFdKQVdWSklQQkBVTVRLREZGUUxWXVg9OicgMDgkNFNdW14UGBwHDExWXFhJXUVZQkRTR0JWX1ZFTUBBUVpdSF1BTllQXERCSElYQ1JcSVM%3D&ru=https%3A%2F%2Fapp.adjust.com%2Ffmvuyq%3Finstall_callback%3Dhttp%253A%252F%252Fwww.startappinstalls.com%252Ftrackinstall%252Fadjust%253Fd%253DECCJP9ZcTmiHuo32YvbLkQ%26campaign%3Dtb_and_sta_disp-all_all_0-100b_all_us_all_all_cpi%26adgroup%3D65437653%26creative%3Drich%26tracker_limit%3D100000&index=0",

campId: "SAP_124875",

title: "Toy Blast",

desc: "The ultimate matching puzzle game with unique magic powers and boosts!Join the fun world of Amy and help collect her precious toys!Match two or more blocks of the same color to clear the level and collect the toys from where they stuck. But be careful! It is not that easy to save all the toys whi...",

img: "http://images.startappservice.com/image/fetch/f_auto,q_80/http%3A%2F%2Fstatic.akamai.startappexchange.com%2Fadvertisers%2F2%2F1098%2F549281_syq1z0w0d3te6cb_Raw.jpg",

icon: "http://images.startappservice.com/image/fetch/f_auto,q_80,w_100,h_100/http%3A%2F%2Flh4.ggpht.com%2FDE_bqJOkCGxh96kysSX9SCEaVlZCQNhTr1s7ap20ufDYIYchruCcyuqF_MyDfMwtTz4",

inPos: "1",

rate: 4.46925,

installs: "1,000,000 - 5,000,000",

isApp: true,

impUrl: "http://www.trackimpression.com/tracking/adImpression?d=IAAAAAAgAAA6X15DSUJEUVZdDUgdRUECX0AERkhIVlQQGF1MDQlYXVcfRRcDS0VCQk1UQFBRSEhJWFtaWFNIRkBZRkFXSVNQU1dATEBFSl5eVl1MRU1WRkVTRVNUX15ETERHXllbWEZIQUkyMyQ%2BRElXWFtRQEdJW19bRVdKQVpSRVpQQEhGX1BPKjEkNl5cX11ORldWR0lMRF5VTVJGRCM1OTBZWVNOR0FCQ0FcIjkmJjwmPCggSl5YVhYQHRMNF1dQR01UTVJLRBMbBEEIBAobEgZPEwQRU0JVUzA1MV09XltZSFdLTkVXUUZSTUFXXVdHWkJAVAwBBksfHBsDEwZPEQAVTVFFREFaXkxcU1gwPSc1MzgtU0NVUzYhWkNFVD0nKC0mJzE5JldSQk0kPiotNzEgIDkrSFZOThIAEREDHx8OMQUXHBRXWlZTJio7OjgkUUBRTTUTCxELFh4RSltdVgMYHwcEUUBVTUdGWlZPSVNAX1I%2BJig1MBUVUUBWTTMqPjozLCQ7SltWVlxKR1pRUUBYTUFVXFNKQEMSRAtYXgZURxFXSllZRxJVQwJKHRZCX10IXQYbSldUQkkgPjQ3ISo2WkVHVCgvJiAmIyE7KDgkU0VRUzUzWkVCVF5eW1VXQ1dURUlQQEBVQFNRT0BJPiYoIkZPQUlQQEBUU0ZWU1BRT0VJOl09SFNPTiMIHBASBAIADw5SOwUHAAELGBZaRUNcQlpQSEBVXFRASkFBXlteXl1MQFdWQkkPFQRLHgYTEhcVBAodRQQUCldWQ0kxNTcsTlBRTkJJDw4CGABaREdcGhFMOTxGWVdPQUVNWVZWWFdKQVdWSklQQkBVTVRLREZGUUxWXVg9OicgMDgkNFNdW14UGBwHDExWXFhJXUVZQkRTR0JWX1ZFTUBBUVpdSF1BTllQXERCSElYQ1JcSVM%3D",

maturity: 0,

advertiser: "Peak Games",

pck: "net.peakgames.amy",

cat: "GAME_PUZZLE"

}

]

}

Creative types and dimensionAppendix

Please only use the following dimensions in the adw and adh parameters for the requested ad type:

HTTP Status Codes

Category list

iOS

I1 Books
I2 Business
I3 Catalogs
I4 Education
I5 Entertainment
I6 Finance
I7 Food & Drink
I8 Games
I9 Health & Fitness
I10 Lifestyle
I11 Medical
I12 Music
I13 Navigation
I14 News
I15 Newsstand
I16 Photo & Video
I17 Productivity
I18 Reference
I19 Social Networking
I20 Sports
I21 Travel
I22 Utilities
I23 Weather

Android

A1 Books & Reference
A2 Business
A3 Comics
A4 Communication
A5 Education
A6 Entertainment
A7 Finance
A8 Health & Fitness
A9 Libraries & Demo
A10 Lifestyle
A11 Live Wallpaper
A12 Media & Video
A13 Medical
A14 Music & Audio
A15 News & Magazines
A16 Personalization
A17 Photography
A18 Productivity
A19 Shopping
A20 Social
A21 Sports
A22 Tools
A23 Transportation
A24 Travel & Local
A25 Weather
A26 Widgets
A27 GAME_ACTION
A28 GAME_ADVENTURE
A29 GAME_ARCADE
A30 GAME_BOARD
A31 GAME_CARD
A32 GAME_CASINO
A33 GAME_CASUAL
A34 GAME_EDUCATIONAL
A35 GAME_FAMILY
A36 GAME_WALLPAPER
A37 GAME_MUSIC
A38 GAME_PUZZLE
A39 GAME_RACING
A40 GAME_ROLE_PLAYING
A41 GAME_SIMULATION
A42 GAME_SPORTS
A43 GAME_STRATEGY
A44 GAME_TRIVIA
A45 GAME_WIDGETS
A46 GAME_WORD
A47 FAMILY_AGES_FIVE_AND_UNDER
A48 FAMILY_AGES_SIX_TO_EIGHT
A49 FAMILY_AGES_NINE_AND_UP
A50 FAMILY_ACTION_AND_ADVENTURE
A51 FAMILY_BRAIN_GAMES
A52 FAMILY_CREATIVITY
A53 FAMILY_EDUCATION
A54 FAMILY_MUSIC_AND_VIDEO
A55 FAMILY_PRETEND_PLAY

Maturity level

The following table maps the maturity level of StartApp to the maturity level of Android and iOS.

 

Network Type Values

0 - Unknown
16 - WIFI
17 - NOT WIFI
1 - GPRS
2 - EDGE
3 - UMTS
4 - CDMA
5 - EVDO revision 0
6 - EVDO revision A
7 - 1xRTT
8 - HSDPA
9 - HSUPA
10 - HSPA
11 - iDen
12 - EVDO revision B
13 - LTE
14 - eHRPD
15 - HSPA+

 

 

Was this article helpful?
2 out of 3 found this helpful
Have more questions? Submit a request

Comments