# Campaign

This document describes how you can use the API to get, edit, and create campaigns, and receive campaign statistics.

# Object description

Before you start using this API endpoint you should know how a campaign object looks. You can find out which fields are mandatory to create a new campaign below.

# Campaign

# Detailed

Property Type Values Constraints Description
campaign_id String any Reference to the campaign
campaign_name String any Display name of the campaign
ad_type String pop, ppr POP or PPR traffic for your campaign
campaign_type String keyword, category, ron keyword: targeting needs keywords categories: targeting needs categories Choose a targeting type: ron: no explicit targeting, keyword: keyword-based targeting category: category-based targeting
status String active, paused, archived Define if your campaign is active, paused or archived
budget Number any At least 10 * cpc Campaign budget
budget_spread Boolean Enable / Disable budget spread
conv_value Number 0.001 <= conv_value <= 9999 Value for conversion tracking
cpc Number budget / 10 at max Cost-per-Click or your bid
url String any The URL we should redirect to
time_settings Time settings Define start and end date or set a campaign schedule
targeting Targeting options Targeting options
whitelisting Boolean If true only traffic from source_ids is allowed If false traffic from source_ids is forbidden
source_ids Array of Strings Black- or whitelisting source_ids
specific_source_ids Array of specific_source_id Add specific bids for source_ids
folder_id number You need an existing folder ID Map campaign in a folder

# Compact

Property Type Values Description
campaignId String Campaign Identifier
name String Campaign display name
status String active, paused, archived Campaign status

# Time settings

Property Type Values Constraints
start_date Date/Time String String in the form of "YYYY-MM-DD HH:mm:ss"
end_date Date/Time String String in the form of "YYYY-MM-DD HH:mm:ss" Must be after start_date and a moment in the future
schedule Object Schedule

# Schedule

The schedule allows you to only run campaigns on specific days of the week during specific hours.

As an example, a campaign that only runs on weekends from 8:00 to 11:59 would be defined by setting schedule to

{
  "sa": [8,9,10,11],
  "su": [8,9,10,11]
}

In general we expect a json object with an array of values between 0 and 23 for each weekday:

{
    "mo": [0, 1, 2, .., 23],
    "tu": [0, 1, 2, .., 23],
    "we": [0, 1, 2, .., 23],
    "th": [0, 1, 2, .., 23],
    "fr": [0, 1, 2, .., 23],
    "sa": [0, 1, 2, .., 23],
    "su": [0, 1, 2, .., 23]
}

# Targeting Options

Property Type Values Constraints Description
country String ISO 3166-1 Alpha 2 country codes. We implemented a helper for you.
traffic_category String adult, non-adult Choose between adult and non-adult traffic
device Array of Strings [desktop] or [mobile] or [desktop, tablet] or [mobile, tablet] Mobile or desktop campaign additionally add tablets on both
keywords Array of Strings Only available if campaign_type is keyword Keywords for targeting
categories Array of numbers Elements are existing category IDs Only available if campaign_type is category Categories for targeting
browsers Array of Strings Each element is one of: firefox, safari, opera, internet_explorer, edge, edge-chromium, chrome, others Target specific browsers
carriers Array of Strings Carrier identifiers. You can look them up with our helper Needs to fit country setting Target specific carriers
os Array of Strings Each element is one of: android, ios, blackberry, macintosh, windows, mobile_others, desktop_others, others Needs to match the device Target specific operating systems

# Operating Systems

The targeting option os can be split into two categories: mobile and desktop operating systems. While android, ios and blackberry are useful in mobile (and tablet) campaigns, macintosh and windows only make sense on desktop (and tablet) campaigns.

others can be used for both if you want to target more operating systems, for example Linux distribution.

Operating Systems are validated depending on device type. If you create a mobile campaign - with or without tablets - you may only pass mobile operating systems. If you create a desktop campaign - without tablets - you may only pass desktop operating systems. Combining desktop and tablet on the other hand allows you to pass mobile and desktop operating systems.

# Source ID Bidding

Property Type Description
source_id String Source ID to bid for
cpc Number Bid

# List Campaigns

Returns a list with all campaigns from a user:

URL : /campaigns

Method : GET

Response-Type: List of compact campaigns

Request example

GET https://api.advertiser.tonic.com/v1/campaigns

Result example

[
	{
		"campaignId": "1",
		"name": "LOLLIPOP_CAMPAIGN",
		"status": "active"
	},
	{
		"campaignId": "2",
		"name": "DONUT_CAMPAIGN",
		"status": "paused"
	},
	{
		"campaignId": "3",
		"name": "BREZEL_CAMPAIGN",
		"status": "archived"
	}
]

# List Campaigns - batch

This endpoint allows to retrieve up to 500 campaigns with campaign details in one API call. Please note, if you skip the parameter fields, the standard endpoint /campaigns will be called instead.

URL : /campaigns?fields=all

Method : GET

Response-Type: Object with list of Detailed Campaigns under key campaigns)

# Query Parameters

Property Mandatory Default Values Description
fields - all, campaign_id, campaign_name, ad_type, campaign_type, budget_spread, budget, cpc, url, whitelisting, status, conv_value, folder_id, targeting, source_ids, specific_source_ids, time_settings Campaign details fields to be included in the result. NOTE: pass all for all the values fields=all or use distinct values, comma separated without blank or space between them, e.g. fields=budget,ad_type
limit 10 1 - 500 Number of rows returned by a query.
page 0 Number of batches to be skipped
offset 0 Skip a number of records in the results. NOTE: If no value for offset is set, then it is calculated using offset = limit * page. If both page and offsetare passed, offset is used, e.g. page=0&offset=100 the 100 lines are skipped.

Request example

GET https://api.advertiser.tonic.com/v1/campaigns?fields=campaign_name,ad_type&page=5&limit=3

Result example

{
    "limit": 3,
    "page": 5,
    "offset": 15,
    "count": 2,
    "campaigns": [
        {
            "campaign_id": "1a2b3c4d5e6f7g8h9i10j11k",
            "campaign_name": "DONUT_CAMPAIGN",
            "ad_type": "pop"
        },
        {
            "campaign_id": "11k10j9i8h7g6f5e4d3c2b1a",
            "campaign_name": "LOLLIPOP_CAMPAIGN",
            "ad_type": "pop"
        }
    ]
}

In this example, there are 17 campaigns altogether. As the offset is set to 15, only 2 campaigns will be returned 2 (despite the fact that the limit is set to 3).

# Get Campaign Details

Returns a campaign identified by the campaignId. Use the list function described above to get all campaigns with their ids.

URL : /campaigns/:campaignId

Method : GET

Response-Type: Detailed campaign

Request example

GET https://api.advertiser.tonic.com/v1/campaigns/1

Result example

If the campaign exists for your account, you will receive:

{
    "campaign_id": "57ee80121c68a18e84e4bcb7",
    "campaign_name": "LOLLIPOP_CAMPAIGN",
    "ad_type": "pop",
    "campaign_type": "ron",
    "budget_spread": true,
    "cpc": 0.046,
    "url": "https://example.com/landingpage",
    "whitelisting": false,
    "status": "active",
    "budget": 100,
    "conv_value": null,
    "folder_id": null,
    "targeting": {
        "country": "US",
        "traffic_category": "non-adult",
        "device": [
            "desktop",
            "tablet"
        ],
        "browsers": [
            "chrome",
            "edge-chromium"
        ],
        "carriers": [],
        "os": [
            "android",
            "ios",
            "blackberry",
            "macintosh",
            "mobile_others"
        ]
    },
    "time_settings": {
        "start_date": "2019-11-25T00:00:00.000Z",
        "end_date": "2020-11-28T23:59:59.000Z",
        "schedule": {}
    }
}

# Create Campaigns

Creates a campaign with the settings sent in the body:

URL: /campaigns

Method: POST

Request type: Detailed campaign

Response type: Detailed campaign

# Mandatory Fields

If you want to reread what each field means, go back to Object Description

If a property is mandatory, there is no default value!

# Campaign

Property Mandatory Default
campaign_name
ad_type
campaign_type
status paused
budget 0 which means the budget is unlimited
budget_spread
conv_value
cpc
url
time_settings null which means it is not time-limited
targeting
whitelisting false
source_ids
specific_source_ids
folder_id

# Time settings

Time settings are optional and may be omitted if you do not want to create a time-limited campaign.

# Targeting Options

Property Mandatory Default
country
traffic_category
device
keywords ✓ - if campaign_type is keyword
categories ✓ - if campaign_type is category
browsers firefox, safari, opera, internet_explorer, edge, edge-chromium, chrome, others
carriers ✓ - if device contains mobile
os android, ios, blackberry, macintosh, windows, mobile_others, desktop_others, others

Request example

This example creates a new PPR campaign:

{
    "campaign_name": "DONUT-CAMPAIGN",
    "ad_type": "ppr",
    "campaign_type": "category",
    "budget_spread": false,
    "cpc": 0.03,
    "url": "http://gph.is/2cpbE6Y",
    "whitelisting": false,
    "status": "active",
    "budget": 3,
    "targeting": {
        "country": "US",
        "traffic_category": "non-adult",
        "device": [
            "mobile"
        ],
        "categories": [1],
        "carriers": ["veri_us"],
        "os": ["android"]
    },
    "time_settings": {
        "start_date": "2016-10-05 00:00:00",
        "end_date": "2020-10-05 00:00:00",
        "schedule": {}
    }
}

This will return:

{
    "campaign_name": "DONUT-CAMPAIGN",
    "ad_type": "ppr",
    "campaign_type": "category",
    "budget_spread": false,
    "cpc": 0.03,
    "url": "http://gph.is/2cpbE6Y",
    "whitelisting": false,
    "status": "active",
    "budget": 3,
    "targeting": {
        "country": "US",
        "traffic_category": "non-adult",
        "device": [
            "mobile"
        ],
        "categories": [
            1
        ],
        "carriers": [
            "veri_us"
        ],
        "os": [
            "android"
        ],
        "browsers": [
            "firefox",
            "safari",
            "opera",
            "internet_explorer",
            "edge",
            "edge-chromium",
            "others",
            "chrome"
        ]
    },
    "time_settings": {
        "start_date": "2016-10-04 22:00:00",
        "end_date": "2020-10-04 22:00:00",
        "schedule": {}
    },
    "conv_value": null,
    "folder_id": null,
    "campaign_id": "5c0fcd89f0220d21d20142b3"
}

# Edit Campaigns

Updates a campaign with properties sent in the body:

URL : /campaigns/:campaignId

Method: PATCH

Request type: Detailed campaign

Response type: Detailed campaign

Request example

This example changes the target url of the campaign with ID 1 to a funny reddit board:

{
	"url": "http://reddit.com/r/holdmybeer"
}

Response Example:

{
    "campaign_id": "1",
    "campaign_name": "LOLLIPOP-CAMPAIGN",
    "ad_type": "ppr",
    "campaign_type": "ron",
    "budget_spread": true,
    "cpc": 0.03,
    "url": "http://reddit.com/r/holdmybeer",
    "whitelisting": false,
    "status": "active",
    "budget": 3,
    "conv_value": 3,
    "folder_id": null,
    "targeting": {
        "country": "US",
        "traffic_category": "non-adult",
        "device": [
            "desktop",
            "tablet"
        ],
        "browsers": [
            "internet_explorer"
        ],
        "carriers": [],
        "os": [
            "windows"
        ]
    },
    "time_settings": {
        "start_date": null,
        "end_date": "2999-12-31 21:59:59",
        "schedule": {}
    }
}

Validation:

Please be aware that changing a campaign has various limitations. For example, you cannot change the ad type (ad_type), set the end date (end_date) in the past and the cost per click (cpc) cannot be below minimum.

# Get Campaign Statistics

With this endpoint you can request statistics of various campaigns:

URL : /campaigns/:campaignId/statistics

Method: GET

Parameters:

Parameter Type Values Description
cluster_by String device, browser, ts, source_id, os, carrier The dimension you want to get a statistic of
interval String days, hours The measure interval; Default: days
from Unix Timestamp or Date 2019-05-01, 1556668800 Start of statistics
to Unix Timestamp or Date 2019-05-01 23:59:59, 1556755199 End of statistics; Value has to be greater than from
device_type String/Array of Strings desktop, mobile, tablet Filter by device_type
browser String/Array of Strings firefox, safari, opera, internet_explorer, edge, edge-chromium, chrome, others Filter by browser
os String/Array of Strings android, ios, blackberry, macintosh, windows, mobile_others, desktop_others, others Filter by os
source_id String/Array of Strings Filter by source_id
carrier String/Array of Strings veri_us Filter by carrier

Response type:

You will get a list of this:

Property Type Description
clustered by String/Number Dimension you clustered by
auctions Number The amount of auctions the campaign was in
clicks Number The amount of actual visits for the campaign
cost Number Summarized costs

Request example:

GET https://api.advertiser.tonic.com/v1/campaigns/1/statistics

Response example

[
    {
        "carrier": "rosh_af",
        "auctions": 10,
        "clicks": 5,
        "cost": 0.05
    },
    {
        "carrier": "etis_af",
        "auctions": 20,
        "clicks": 7,
        "cost": 0.07
    }
]
Last Updated: 9/13/2021, 11:50:41 AM