Campaigns Creation API (V 2.1.18) – Start.io

Introduction

The Advertiser Campaign API allows you to instantly create and update your campaigns through direct communication between your system and Start.io (Formerly StartApp) advertising platform.
The Campaign API allows you to easily manage your campaigns with no need to login to the Start.io ( Formerly 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 Start.io's campaign creation API, please create your account on Start.io's portal , 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.start.io/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:
Get campaigns 3000607:
https://api.start.io/adv/campaign/1.0?partner=accountId&token=accountToken&campaig
nId=3000607
Get last updated 200 paused and active campaigns:
https://api.start.io/adv/campaign/1.0?partner=accountId&token=accountToken&status=
paused,active&limit=200
Get last updated 100 campaigns:
https://api.start.io/adv/campaign/1.0?partner=accountId&token=accountToken&
limit=100

Get Campaigns Ids - HTTP GET

Get all campaigns ids.

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

Response: Array<JSON>

Get specific campaigns by campaigns Ids - HTTP POST

URL:
https://api.start.io/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 campaign - HTTP POST:

URL: https://api.start.io/adv/campaign/1.0?partner=accountId&token=accountToken
Header: Content-Type: application/json
Body: JSON
Result: JSON:

i. Success message containing generated campaign Id:

{
  "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 theapp	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

(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 with most targeting options:


{
  "campaignType": {
    "destinationUrl": "https://play.google.com/store/apps/details?id=com.gamehour.barcaDash"
  },
  "campaignInfo": {
    "name": "Barca56",
    "startDate": "2018-01-26",
    "endDate": "2018-02-28T08:00",
    "hasEndTime": true,
    "dayParting": [
      {
        "from": "2018-01-25T01:00",
        "to": "2018-01-25T22:00",
        "day": "sunday"
      },
      {
        "from": "2018-01-25T02:00",
        "to": "2018-01-25T03:00",
        "day": "saturday"
      }
    ]
  },
  "targeting": {
    "geo": {
      "countries": {
        "exclude": false,
        "value": [
          {
            "countryKey": "US"
          }
        ]
      }
    },
    "device": {
      "connectionType": "WIFI",
      "osVersion": {
        "max": {
          "versionName": "All"
        },
        "min": {
          "versionName": "5.1"
        }
      },
      "deviceType": "mobile"
    },
    "optimization": {
      "devId": {
        "exclude": false,
        "value": [
          "104111111",
          "104222222",
          "104333333"
        ]
      },
      "appId": {
        "exclude": true,
        "value": [
          "212111111",
          "212222222",
          "212333333"
        ]
      },
      "publisherAppCategory": {
        "exclude": true,
        "value": [
          "Education",
          "Business"
        ]
      }
    },
    "placements": {
      "adTypes": [
        "fullPage",
        "appWall",
        "smallBanner"
      ]
    }
  },
  "budget": {
    "bidPrice": 2.5,
    "pricingModel": "CPM",
    "dailyBudget": 60,
    "totalBudget": 10000
  },
  "creativeList": [
    {
      "name": "My Banner Creative",
      "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"
        }
      ]
    },
    {
      "name": "My Rich Text Creative",
      "creativeType": "richText",
      "url": "https://play.google.com/store/apps/details?id=com.mcentric.mcclient.FCBWorld"
    },
    {
      "name": "My Interstitial Creative",
      "creativeType": "interstitial",
      "url": "https://play.google.com/store/apps/details?id=com.mcentric.mcclient.FCBWorld",
      "images": [
        {
          "url": "http://dummyimage.com/320x480/000/fff.png&text=Barca"
        },
        {
          "url": "http://dummyimage.com/480x320/000/fff.png&text=Barca"
        }
      ]
    }
  ],
  "customFields": {
    "customField1": "somefield",
    "customField2": "anotherfield"
  }
}

Targeting Categories

Value list for targeting.optimization.publisherAppCategory.value

iOS Categories:

Other,
Books,
Business,
Catalogs,
Education,
Entertainment,
Finance,
Food & Drink,
Games,
Health & Fitness,
Lifestyle,
Medical,
Music,
Navigation,
News,
Photo & Video,
Productivity,
Reference,
Social Networking,
Sports,
Travel,
Utilities,
Weather,
Shopping,
Magazines & Newspapers,
Stickers

Creative Guidelines

Android

Creative	Ad type	Dimensions in pixels (limit file size in KB)
Banner	smallBanner	300X50(150), 320X50(150), 480X32(150), 728X90(150), 468X60(150), 1024X90(150), 1200X628(250), 1200X627(250)
	bigBanner	300x250(150)
Interstitial	fullPage	320X480(150), 768X1024(250) for portrait 480X320(150), 1024X768 (250) for landscape
	appWall	320X480(150), 768X1024(250) for portrait 480X320(150), 1024X768 (250) for landscape
Rich Text	smallBanner	160x160(100), 175x175(100), 180x180(150), 300x300(150), 512x512(200), 1024x1024(400)
	fullPage	160x160(100), 175x175(100), 180x180(150), 300x300(150), 512x512(200), 1024x1024(400)
	largeBanner	1200X628(250), 1200X627(250)
	appWall	160x160(100), 175x175(100), 180x180(150), 300x300(150), 512x512(200), 1024x1024(400)
Video	Video file	MP4 & webm. Up to 100MB
	Post Roll Image	any size. Up to 250KB

iOS

Creative	Ad Type	Dimensions in pixels (limit file size in KB)
Banner	smallBanner	300X50(150), 300X250(150), 320X50(150), 480X32(150), 728X90 (150), 468X60(150), 1024X90 (150), 1200X628(250), 1200X627 (250).
Interstitial	fullPage	320X480(150), 768X1024(250) for portrait 480X320(150), 1024X768 (250) for landscape
Rich Text	smallBanner	160x160(100), 175x175(100), 300x300(150), 512x512(200), 1024x1024(400)
	fullPage	160x160(100), 175x175(100), 300x300(150), 512x512(200), 1024x1024(400)
	largeBanner	1200X628(250), 1200X627(250)
Video	Video file	MP4 & webm. Up to 100MB
	Post Roll Image	any size. Up to 250KB

File extensions: jpg, jpeg, gif, png

Update campaign/creative - HTTP PUT:

URL: https://api.start.io/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 campaign Id:

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

Error message containing description:

{
  "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://dummyimage.com/480x320/000/fff.png&text=Barca5"
        },
        {
          "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 Start.io's (Formerly StartApp) servers and may be extracted on the "read" campaigns API).