Campaigns Creation API (V 2.1.18)

Introduction 

The Advertiser Campaign API allows you to instantly create and update your campaigns through direct communication between your system and StartApp advertising platform.
The Campaign API allows you to easily manage your campaigns with no need to login to the StartApp portal.
The API conforms to the RESTful design principles. Advertisers interact with the resources exposed via the API by accessing resource collection and element URIs using the HTTP verbs (GET, POST, and PUT). Advertiser Campaign API accepts and returns only JSON data.
In order to use StartApp's campaign creation API, please create your account on StartApp's portal (https://portal.startapp.com/#/signup), an API token will be provided by your Account Manager. You will be requested to provide your server’s IP address.
Note that in case of a request error you will receive an error id. Please save this id as you will be requested to provide it to our support.

Read Campaigns - HTTP GET

URL: https://api.startapp.com/adv/campaign/1.0?partner=accountId&token=accountToken

Headers:

Header Value Mandatory Description
Accept-Encoding gzip no Compress response data in gzip format. ‘Content-Encoding:gzip’ header will be added to the response headers.

Parameters:
You can choose to get specific campaigns on the API:

Field Description Type Mandatory Values
campaignId Get campaign by
campaign id
number no Campaign id.
For example: 3123456
status Get campaigns by status s array no draft, pending, paused, active,
denied, archived
default: all
limit Limit of the
total campaigns
presented
number no 1-200
default: 200

Read Examples:
Read Examples:
Get campaigns 3000607:
https://api.startapp.com/adv/campaign/1.0?partner=accountId&token=accountToken&campaig
nId=3000607
Get last updated 200 paused and active campaigns:
https://api.startapp.com/adv/campaign/1.0?partner=accountId&token=accountToken&status=
paused,active&limit=200
Get last updated 100 campaigns:
https://api.startapp.com/adv/campaign/1.0?partner=accountId&token=accountToken&
limit=100

Get Campaigns Ids - HTTP GET

Get all campaigns ids.

URL:
https://api.startapp.com/adv/campaign/1.0/campaigns?partner=accountId&token=accountT
oken

Response: Array<JSON>

Get Campaigns by campaigns Ids - HTTP POST

URL:
https://api.startapp.com/adv/campaign/1.0/campaigns?partner=accountId&token=accountT
oken

Header: Content-Type: application/json

Body: JSON

Field Description Type Mandatory Values
campaignId Requested campaign
ids (maximum 200
campaigns)
Array<string> yes For example:
[“311111”, “3222222”]

Result: Array<JSON>


{
  "campaignId": [
    "3111111",
    "3222222",
    "333333"
  ]
}

Create campaigns - HTTP POST:

URL: https://api.startapp.com/adv/campaign/1.0?partner=accountId&token=accountToken
Header: Content-Type: application/json
Body: JSON
Result: JSON:
i. Success message containing generated camaignId:


{
 "success": true,
 "campaignId": "3123456"
}

ii. Error message containing description:


{
 "success": false,
 "message": "Create campaign error: 'This campaign name already exists
 on your account'"
}

JSON Structure

Campaign Type

Field Description Type Mandatory Values
destinationUrl App link from Google
Play or App store
url  yes  
Platform  App platform  string no  ios, android
default: automatic 
category The category of the
app
string   Only for web
destinationUrl 
See in this list

Campaign Info

Field Description Type Mandatory Values
name Campaign name url  yes  
startDate Start date of the
campaign
date  no  default: now
hasStartTime Use the time from
startDate
boolean  no  true, false
default: false
endDate End date of the campaign date  no  
hasEndTime Use the time from
endDate
boolean  no  true, false
default: false
dayParting Select specific days and/or hours for your campaign to run.
All selected times are in GMT.
Please note:selected times refer to
the ad request time, and not necessarily the impression time
array<dayParting>  no See Day Parting table

Day Parting

Field Description Type Mandatory Values
from  Start time date no  
to  End time date no  
day The day for this day parting string no all_week, sunday, monday, tuesday, wednesday, thursday, friday, saturday

Targeting

Geo - countries

Field Description Type Mandatory Values
exclude  When exclude=false,
the values are a white list (target only specific geos); when exclude=true, the values are a black list (target all geos except the specified)
boolean no true, false
default: false
value Array of countries array< countryKey> no See Country Object table
default: [] (all countries)

Country Object

Field Description Type Mandatory Values
countryKey  Add a country or list of countries to the white
or black list
string no Country key according to ISO 3166-1 alpha-2

Currently, the API does not support City and Carrier targeting.

Device

Field Description Type Mandatory Values
connectionType Target by Connection Type string no ALL, WIFI, NO_WIFI
default: ALL 
osVersion Target by Max./Min. OS version object  no  
deviceType Target by Device Type string no all, mobile, tablet
default: all

OS Version

Field Description Type Mandatory Values
max.versionName Target the maximum OS
Version
 string no default: all
min.versionName Target the minimum OS
Version
 string no default: all

Currently, the API does not support Device Manufacturer and Device Language targeting.

Optimization

Field Description Type Mandatory
devId Target specific publishers or block
specific publishers from displaying
your ads by adding their publisher
IDs to the Whitelist or Blacklist
object  no
appId Target specific apps or block
specific apps from displaying your
ads by adding their App IDs to the
Whitelist or Blacklist
object  no
publisher
AppCate
gory
Target your campaign only to apps
with specific app categories. Please
note that choosing specific
categories might severely reduce
the amount of traffic your
campaign will receive
object  no
channels Target the traffic source for your
campaign.
object  no
bundleId Target specific package / bundle or
block specific package / bundle
from displaying your ads by adding
their bundle IDs to the Whitelist or
Blacklist
object  no

Publisher ID (devId)

Field Description Type Mandatory Values
exclude When exclude=false, the values are a whitelist (target only specific publisher IDs); when exclude=true, the values are a blacklist
(target all Publisher iDs except the specified)
boolean no true, false
 value List of publisher IDs to white/blacklist  array<string> no  

App ID (appId)

Field Description Type Mandatory Values
 exclude When exclude=false, the values are a
whitelist (target only specific App IDs);
when exclude=true, the values are a
blacklist (target all App IDs except the
specified)
 boolean  no  true, false
 value  List of app IDs to white/blacklist  array<string>  no  

Publisher App Category

Field Description Type Mandatory Values
exclude When exclude=false, the values are a whitelist(target only specific publisher
app categories); when exclude=true,
the values are a black list (target all
publisher app categories except the
specified)
boolean no true, false
value List of publisher app categories to white/black list array<string>  no See categories options
default: [] (all)

Bundle IDs

Field Description Type Mandatory Values
exclude When exclude=false, the values are a
white list (target only specific bundle
ID); when exclude=true, the values are a black list (target all bundle IDs except the specified)
boolean no true, false
exclude List of bundle IDs to white/black list array<string> no Example:
‘com.google.andr
oid.gm’.
default: [] (all)

Channels

Field Description Type Mandatory Values
value  List of supported channels  array<string> no sdk,
programmatic
default: [] (all)

Audience

Field Description Type Mandatory Values
targetAdv
ertiserId
When targetAdvertiserId=true,
the campaign will be
limited to users who allow
us to collect their
advertiser ID. This will
require you to user our
advertising ID macro
(startapp_advertising_id)
in your tracking links.
Boolean no true,false 

Ad Types

Field Description Type Mandatory Values
adTypes

List of Ad Types you can target

array<string> no fullPage, appWall,
smallBanner, bigBanner
default: [] (all)

Budget & Bid

Field Description Type Mandatory Values
totalBudget The total budget of the campaign,lifetime, accumulated number no default: unlimited
dailyBudget The daily budget of the campaign.
Please note that daily spend may
reach up to 20% over your daily budget
number no default: unlimited
pricingModel The pricing model of the campaign  string  yes CPC, CPM
bidPrice The bid price of the campaign. The minimum bid is set according to the targeting you specified.
Please note that minimum bids may vary
from time to time 
number yes  

Creative

Field Description Type Mandatory Values
name The Creative name, for
your personal use
string yes  
url Valid tracking URL to your
designated landing page
url yes  
images  The creative image files.
See Guidelines here
array<image> yes (except
rich text)
 
creativeType  The type of the Creative  string yes  banner,
interstitial,
richText 

Image Object

Field Description Type Mandatory Values
url The URL of the creative image, the API
will download and save it 
url yes  

Custom Fields (customFields)

(optional) A free-form field for your own use. You can specify up to 2 custom fields.

Character length and limitations: value can contain only letters and numbers, up to 200
characters.

Create Examples:

Only mandatory fields:


{
"campaignType": {
"destinationUrl": "https://play.google.com/store/apps/details?id=com.gamehour.barcaDash"
},
"campaignInfo": {
"name": "Barca50"
},
"budget": {
"pricingModel": "CPC",
"bidPrice": 0.008
},
"creativeList": [
{
"name": "Banner 1",
"url": "https://play.google.com/store/apps/details?id=com.mcentric.mcclient.FCBWorld",
"creativeType": "banner",
"images": [
{
"url": "http://dummyimage.com/320x50/000/fff.png&text=Barca"
}
]
}
]
}

Add targeting to US:


{
"campaignType": {
"destinationUrl": "https://play.google.com/store/apps/details?id=com.gamehour.barcaDash"
},
"campaignInfo": {
"name": "Barca51"
},
"budget": {
"pricingModel": "CPC",
"bidPrice": 0.03
},
"targeting": {
"geo": {
"countries": {
"exclude": false,
"value": [
{
"countryKey": "US"
}
]
}
}
},
"creativeList": [
{
"name": "Banner 1",
"url": "https://play.google.com/store/apps/details?id=com.mcentric.mcclient.FCBWorld",
"creativeType": "banner",
"images": [
{
"url": "http://dummyimage.com/320x50/000/fff.png&text=Barca"
}
]
}
]
}

Add targeting to the programmatic channel:


{
"campaignType": {
"destinationUrl":
"https://play.google.com/store/apps/details?id=com.gamehour.barcaDash"
},
"campaignInfo": {
"name": "Barca51"
},
"budget": {
"pricingModel": "CPC",
"bidPrice": 0.03
},
"targeting": {
"optimization": {
"channels": {
"value": [
"programmatic"
]
}
}
},
"creativeList": [
{
"name": "Banner 1",
"url":
"https://play.google.com/store/apps/details?id=com.mcentric.mcclient.FCBWorld",
"creativeType": "banner",
"images": [
{
"url": "http://dummyimage.com/320x50/000/fff.png&text=Barca"
}
]
}
]
}

Web campaign:


{
"campaignType": {
"destinationUrl": "https://www.2chef.co.il",
"category": "Business",
"platform": "android"
},
"campaignInfo": {
"name": "2 chef"
},
"budget": {
"pricingModel": "CPC",
"bidPrice": 0.008
},
"creativeList": [
{
"name": "Banner 1",
"url": "https://www.2chef.co.il",
"creativeType": "banner",
"images": [
{
"url": "http://dummyimage.com/320x50/000/fff.png&text=2chef"}
]
}
]
}

Request example:

Click here for an example with most options.

Targeting Categories

Value list for targeting.optimization.publisherAppCategory.value

Android Categories:

Other, Shopping, GAME_PUZZLE,

Books & Reference, Social, GAME_RACING,

Business, Sports, GAME_ROLE_PLAYING,

Comics, Tools, GAME_SIMULATION,

Communication, Transportation, GAME_SPORTS,

Education, Travel & Local, GAME_STRATEGY,

Entertainment, Weather, GAME_TRIVIA,

Finance, Widgets, GAME_WIDGETS,

Health & Fitness, GAME_ACTION, GAME_WORD,

Libraries & Demo, GAME_ADVENTURE, Family Ages 5 & Under,

Lifestyle, GAME_ARCADE, Family Ages 6-8,

Live Wallpaper, GAME_BOARD, Family Ages 9 & up,

Media & Video, GAME_CARD, Family Action & Adventure,

Medical, GAME_CASINO, Family Brain Games,

Music & Audio, GAME_CASUAL, Family Creativity,

News & Magazines, GAME_EDUCATIONAL, Family Education,

Personalization, GAME_FAMILY, Family Music & Video,

Photography, GAME_WALLPAPER, Family Pretend Play

Productivity, GAME_MUSIC,

iOS Categories:

Other, Music,

Books, Navigation,

Business, News,

Catalogs, Newsstand,

Education, Photo & Video,

Entertainment, Productivity,

Finance, Reference,

Food & Drink, Social Networking,

Games, Sports,

Health & Fitness, Travel,

Lifestyle, Utilities,

Medical, Weather

Creative Guidelines

Android

Creative Placement Dimensions (limit size in KB)
Banner smallBanner

300x50(150), 320x50(150), 480x32(150), 468x60(150), 728x90(150), 1024x90(150)

  bigBanner 300x250(150)
Interstitial fullPage 480x320(150), 1024x768(250)
  appWall 480x320(150), 1024x768(250)
Rich Text smallBanner

160x160(100), 175x175(100), 300x300(150), 512x512(200), 1024x1024(400)

  fullPage

160x160(100), 175x175(100), 300x300(150), 512x512(200), 1024x1024(400)

  appWall

160x160(100), 175x175(100), 300x300(150), 512x512(200), 1024x1024(400)

iOS

Creative Placement Dimensions (limit size in KB)
Banner smallBanner 320x50(150), 480x32(150), 468x60(150), 728x90(150), 1024x90(150)
Interstitial fullPage 480x320(150), 1024x768(250)
Rich Text smallBanner

160x160(100), 175x175(100), 300x300(150), 512x512(200), 1024x1024(400)

  fullPage

160x160(100), 175x175(100), 300x300(150), 512x512(200), 1024x1024(400)

File extensions: jpg, jpeg, gif, png

Update campaign/creative - HTTP PUT:

URL:https://api.startapp.com/adv/campaign/1.0?partner=accountId&token=accountToken
Header: Content-Type: application/json
Body: Same as Create campaign (POST) + add campaignId (In the JSON)
Result: JSON (same as create):

Success message containing generated campaignId:


{
"success": true,
"campaignId": "3123456"
}

Error message containing description:455


{
"success": false,
"message": "Create campaign error: 'This campaign name already exists on
your account'"
}

Update Examples

Update campaign status:


{   
"campaignId": "3123456",
"status": "paused"
} 

Update campaign name for example:


{
"campaignId": "3123456",
"campaignInfo":{
"name":"New campaign name"
}
}

Update end date:


{
"campaignId": "3123456",
"campaignInfo": {
"endDate": "2018-03-18"
}
}

Update creative name for example:


{
"campaignId": "3123456",
"creativeList": [
{
"creativeId": "4123",
"name": "New creative name"
}
]
}

Change day parting (will overwrite the old one):


{
"campaignId": "3123456",
"campaignInfo": {
"dayParting": [
{
"from": "2018-04-20T10:00",
"to": "2018-04-20T14:00",
"day": "monday"
}
]
}
}

Change countries in targeting (will overwrite the old one):


{
"campaignId": "3123456",
"targeting": {
"geo": {
"countries": {
"value": [
{
"countryKey": "ES"
},
{
"countryKey": "TW"
},
{
"countryKey": "NZ"
}
]
}
}
}
}

Update max OS version:


{
"campaignId": "3123456",
"targeting": {
"device": {
"osVersion": {
"max": {
"versionName": "5.1"
}
}
}
}
}

Remove OS version targeting form campaign:


{
"campaignId": "3123456",
"targeting": {
"device": {
"osVersion": null
}
}
}

Update daily budget:


{
"campaignId": "3123456",
"budget": {
"dailyBudget": 318
}
}

Add creative:


{
"campaignId": "3123456",
"creativeList": [
{
"url": "https://play.google.com/store/apps/details?id=com.mcentric.mcclient.FCBWorld",
"images": [
{
"url": "http://dummyimage.com/320x50/000/fff.png&text=Barca"
}
],
"creativeType": "banner",
"name": "My new creative"
}
]
}

Update creative status (you must send creativeId):


{
"campaignId": "3123456",
"creativeList": [
{
"creativeId": "41440",
"status": "paused"
}
]
}

Update creative image (You must send creativeId and URL of the image that you want to update according to the read API):


{
"campaignId": "3123456",
"creativeList": [
{
"creativeId": "41443",
"images": 
[
{
"url": "http://s3.startapp.com.s3.amazonaws.com/advertis-
ers/104208995/1205/14438991e973-93e0-4c99-aea0-11f17908fe58.png&text=Barca"
},
{
"url": "http://dummyimage.com/480x320/000/fff.png&text=Barca2"
}
]
}
]
}

Please note that updating a creative image URL or tracking URL will require re-approval of your creative. If you wish to update your creative name only, you may pass only the name value on the JSON, or make sure to use the exact same tracking URL and/or Image URL (as generated by StartApp's servers and may be extracted on the "read" campaigns API).

Was this article helpful?
0 out of 0 found this helpful