Campaign Optimization API

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':
3 months back.

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

Important note:

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

Important note:

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

Was this article helpful?
Have more questions? submit a request