Introduction
The Campaign Optimization API allows you to instantly optimize your campaign by setting
different bids for different publishers, applications, and other targeting, all in one action.
The Optimization API allows you to easily manage your campaigns through direct communication
between your system and Start.io’s (Formerly StartApp) advertising platform, with no need to login to the Start.io portal.
The API conforms to the RESTful design principles. Advertisers interact with the resources exposed
via the API by accessing resource collection and element URLs using the HTTP verbs (GET, POST,
and PUT).
Campaign Optimization API accepts and returns only JSON data.
In order to use Start.io's Campaign Optimization API, please create an account on Start.io's
portal ( https://portal.start.io/#/signup ) An API token will be provided by your Account
Manager.
1. Get Campaign Optimization for a campaign – HTTP POST
1.1. URL:
https://api.start.io/adv/campaignOptimization/1.0/optimize?partner=accountId
&token=accountToken
1.2. Header: Content-Type: application/json
1.3. Body: JSON
JSON Structure:
Field | Description | Type | Mandatory | Values |
campaignIds | Get campaign optimization for a campaign id |
Array<string> | Yes | Campaign Id |
dimensions | Dimension to analyze | String | Yes | publisher, application, country, carrier, connectionType, deviceType, creative, adType |
startDate | Filter campaign optimization by start date |
Date | No |
I. Both ‘startDate’ and‘endDate’ are required. II. Minimum value for 'startDate': III. Default – last 7 days. |
endDate | Filter campaign optimization by end date |
Date | No | |
limit | Maximum number of results returned | Number | No | Number of results. Default - 5000. 0 - no limit. |
orderBy | Sort results by value | String | No | impressions, clicks conversions, spent Maximum values shown first Default - spent |
getSummary | If true, get campaign summary |
Boolean | No | Default – false |
1.4. Example
{
"campaignIds": [
"123456"
],
"dimensions": [
"publisher"
],
"limit": 300,
"orderBy": "impressions",
"startDate": "2017-04-02T00:00:00.000Z",
"endDate": "2017-04-10T00:00:00.000Z",
"getSummary": true
}
1.5. Result
1.5.1. Success result: Array
Field | Description | Type |
data | Optimization data | Array<JSON> |
summary | Campaign summary | Array<JSON> |
I. data JSON:
Each JSON will include the requested dimension event ids. For example, for ‘publisher’ dimension:
{
"publisher" : "123456"
}
For ‘country’ dimension:
{
"country": "AR"
}
In addition, will include the following fields:
Field | Description |
impressions | The number of times that the ad has been presented |
clicks | The total number of clicks |
conversions | The total number of installs |
spent | The amount of USD spent for the relevant conversions |
ctr | Clicks/impressions |
cr | Installs/clicks |
cpa | Spent/conversions |
bidPrice | Amount spent |
II. summary JSON (optional)
Field | Description |
impressions | The number of times that the ad has been presented |
clicks | The total number of clicks |
conversions | The total number of installs |
spent | The amount of USD spent for the relevant conversions |
ctr | clicks/impressions |
cr | installs/clicks |
cpa | spent/conversions |
1.5.2. Error result: JSON
{
"message": "Cannot find campaign for user",
"success": false
}
2. Update Campaign Optimization for a campaign- HTTP PUT
2.1. URL:
https://api.start.io/adv/campaignOptimization/1.0/optimize?partner=accountId
&token=accountToken
2.2. Header: Content-Type: application/json
2.3. Body: JSON
If a request for an event fails, the entire update will fail.
JSON Structure:
Field | Description | Type | Mandatory | Values |
campaignId | Update campaign optimization for a campaign id |
Array<string> | Yes | Campaign id Example- [“123456”] |
optimization | Campaign optimization data |
OptimizationObject (See 2.3.1) | Yes | Note- ‘null’ will reset Bids for all targeting (see examples in 2.4) |
2.3.1. Optimization object:
Key | Value |
Specific dimension (publisher, application, country, carrier, connectionType, deviceType, adType) |
DimensionObject (See 2.3.2) Note- ‘null’ will reset Bids for this dimension (see example) |
2.3.2. Dimension object:
Key | Value |
‘dimensionEventId’ - specific dimension event id (publisher id, application id, country, etc.) | BidObject (See 2.3.3) |
2.3.3. Bid object:
Key | Description | Type | Mandatory |
bid | Bid price for event. | Number | Yes |
2.4. Examples
i. Update bids for publishers and applications
{
"campaignId": "123456",
"optimization": {
"publisher": {
"111111111": {
"bid": 0.07
},
"222222222": {
"bid": 0.06
}
},
"application": {
"333333333": {
"bid": 0.007
},
"444444444": {
"bid": 0.005
},
"555555555": {
"bid": 0.006
}
}
}
}
ii. Update bids for country and deviceType:
{
"campaignId": "123456",
"optimization": {
"country": {
"ID": {
"bid": 0.07
},
"TH": {
"bid": 0.06
}
},
"deviceType": {
"MOBILE": {
"bid": 0.008
}
}
}
}
iii. Reset bids for all targeting:
{
"campaignId": "123456",
"optimization": null
}
iv. Reset bids for ‘publisher’ dimension only:
{
"campaignId": "123456",
"optimization": {
"publisher": null
}
}
2.5. Result
2.5.1. Success result
{
"success": true,
"campaignId": "123456"
}
2.5.2. Error result
{
"success": false,
"message": "API Error: Cannot find campaign."
}
3. Update a Campaign’s Targeting (Blacklist) – HTTP PUT
3.1. URL:
https://api.start.io/adv/campaignOptimization/1.0/blacklist?partner=accountId&
token=accountToken
3.2. Header: Content-Type: application/json
3.3. Body: JSON
If a request for an event fails, the entire update will fail.
JSON Structure
Field | Description | Type | Mandatory | Values |
campaignId | Include or exclude event ids (‘dimensionEventIds’) for a campaign | Array<string> | Yes | |
dimensionEventIds | A list of event ids to include / exclude | Array<string> | Yes | Event ids received in POST request For device type and connection type: ALL- will include all event ids. |
dimension | Target or block specific publisher, application, country, etc | Array<string> | Yes | publisher, application, country, carrier, connectionType, deviceType, adType |
include | If true, the event ids in ‘dimensionEventIds’ will be included.If false, will be excluded | Boolean | Yes | true, false |
3.4. Examples
{
"campaignId": "123456",
"dimensionEventIds": [
"123456789"
],
"dimension": "publisher",
"include": false
}
{
"campaignId": "123457",
"dimensionEventIds": [
"MOBILE"
],
"dimension": "deviceType",
"include": true
}
{
"campaignId": "123457",
"dimensionEventIds": [
"WIFI"
],
"dimension": "connectionType",
"include": true
}
3.5. Result
3.5.1. Success result
{
"success": true,
"campaignId": "123456"
}
3.5.2. Error result
{
"success": false,
"message": "API Error: Cannot find campaign."
}
4. Get a Campaign’s Bids– HTTP GET
4.1. URL
https://api.start.io/adv/campaignOptimization/1.0/campaignBids?partner=accountId
&token=accountToken
4.2. Parameters
Field | Description | Type | Mandatory |
campaignId | Get bids for a campaign. | number | Yes |
4.3. Read example
4.3.1. Get bids for campaign id 123456
https://api.start.io/adv/campaignOptimization/1.0/campaignBids?partner=accountId&toke
n=accountToken&campaignId=123456