Campaign API (ENG)

Campaign API (ENG)

Introduction

This API is used to manage Campaigns. You can create new Campaigns, edit existing Campaigns and create/edit Schedules for Campaigns.
You can also get information about Campaigns.

API PATH

/api/campaign

API CALLS

Add/Edit Campaign

Creates a new Campaign specified by the 'type' -parameter, or updates an existing Campaign if the 'campaignId' -parameter is provided.

REQUEST

Method: POST
Parameters:


Name
Value
Requirement
Info
action
addUpdateCampaign
Mandatory

organizationId
Number
Mandatory
Icareus Suite Organization Identifier
token
String
Mandatory
Secret key of the Organization
userId
Number
Mandatory
Icareus Suite User Identifier (Must be a Affiliate Administrator or Ismaccount Administrator)
type
String
Mandatory
The type of the Campaign being created / edited. One of: videoswap, switchin, activead, instreamvideo, invideooverlay
data
String
Optional
Encoded JSON Object containing the Campaign data.

NOTE: The JSON Object containing the data for the Campaign can either be provided through the 'data' -parameter as an encoded string. Or the JSON Object can be provided in the request body.
The content of the Campaign data JSON object varies between different Campaign types.

Video Swap Campaign Data


JSON Object expected when creating/editing a Video Swap Campaign:

Key
Value
Requirement
Info
name
String
Mandatory
Name of the Campaign
cpmPrice
Number
Mandatory
A number greater than or equal to 0
VASTProfileId
Number
Mandatory
Icareus Suite VAST Profile Identifier
channels
Array
Optional
An array of Icareus Suite Linear Channel Identifiers. Video Swap Campaign can only have 1 Linear Channel identifier specified.
safetyMargin
Number
Optional
Safety Margin size. Default: 0
dataSource
Number
Optional
Campaign Data Source. Either 1 (Digita Playlist) or 4 (CCMS Playlist). Default: 1
targeting
Object
Optional
Campaign Targeting. See: Targeting Object
deviceTypeBlacklist
Array
Optional
An array of Icareus Suite Device Type Identifiers. Only provide either deviceTypeBlacklist or deviceTypeWhitelist, not both.
deviceTypeWhitelist
Array
Optional
An array of Icareus Suite Device Type Identifiers. Only provide either deviceTypeBlacklist or deviceTypeWhitelist, not both.
adBreaks
Array
Optional


Example Video Swap Data Object:
  1. {
      "name": "API VideoSwap Example",
      "safetyMargin": 25,
      "dataSource": 1,
      "channels": [
        56810
      ],
      "VASTProfileId": 479862,
      "cpmPrice": 0,
      "targeting": {
        "params": [
          {
            "name": "regionId",
            "value": "004"
          }
        ]
      }
    }


Active Ad Campaign Data

JSON Object expected when creating/editing an Active Ad Campaign:

Key
Value
Requirement
Info
name
String
Mandatory
Name of the Campaign.
bannerVisibleTime
Number
Mandatory
Visible time in seconds.
bannerInteractionTime
Number
Mandatory
Interaction time in seconds.
cpmPrice
Number
Mandatory
A number greater than or equal to 0.
channels
Array
Optional
An array of Icareus Suite Linear Channel Identifiers.
customInputData
Object
Optional
Custom Channel Input Data Object
maxShowsPerCampaign
Number
Optional
Maximum Campaign Impressions.
mediaIds
Array
Optional
An array of mediaId's
displayTimes
String
Optional
Comma separated list of timestamps. (milliseconds elapsed since the UNIX epoch (Jan 1, 1970)).
adPlatform
Number
Optional
Ad Platform. Either: 1 (Icareus Suite) or 2 (AdForm). Default: 1
adTagUrl
String
Optional
Ad Tag URL. Required when Ad Platform is 2 (AdForm).
adFormCreativeType
Number
Optional
AdForm Creative Type. See: Valid Creative Types. Default: 1  (Only relevant when Ad Platform is 2 (AdForm)
creativeId
Number
Optional
Icareus Suite Creative Identifier. Default: 0 (Only relevant when Ad Platform is 1 (Icareus Suite)
dataSource
Number
Optional
Campaign Data Source. Either 2 (Pebble TV Playlist) or 3 (User/Custom Input). Default: 2
targeting
Object
Optional
Campaign Targeting. See: Targeting Object
reconcileKeys
Array
Optional
Reconcile Keys Array.
deviceTypeBlacklist
Array
Optional
An array of Icareus Suite Device Type Identifiers. Only provide either deviceTypeBlacklist or deviceTypeWhitelist, not both.
deviceTypeWhitelist
Array
Optional
An array of Icareus Suite Device Type Identifiers. Only provide either deviceTypeBlacklist or deviceTypeWhitelist, not both.

Example Active Ad Data Object:
  1. {
      "name": "API Active Ad Example",
      "channels": [
        56810,
        57067
      ],
      "adPlatform": 1,
      "dataSource": 2,
      "mediaIds": [],
      "creativeId": 652313,
      "displayTimes": "1574946000000,1574960400000",
      "bannerVisibleTime": 20,
      "bannerInteractionTime": 10,
      "maxShowsPerCampaign": 50,
      "cpmPrice": 0,
      "targeting": {
        "params": [
          {
            "name": "regionId",
            "value": "004"
          }
        ]
      },
      "deviceTypeWhitelist": [
        13700
      ]
    }


Switch In Campaign Data

JSON Object expected when creating a Switch In Campaign:

Key
Value
Requirement
Info
name
String
Mandatory
Name of the Campaign.
bannerVisibleTime
Number
Mandatory
Visible time in seconds.
bannerInteractionTime
Number
Mandatory
Interaction time in seconds.
cpmPrice
Number
Mandatory
A number greater than or equal to 0.
channels
Array
Optional
An array of Icareus Suite Linear Channel Identifiers.
customInputData
Object
Optional
Custom Channel Input Data Object
adPlatform
Number
Optional
Ad Platform. Either: 1 (Icareus Suite) or 2 (AdForm). Default: 1
dataSource
Number
Optional
Campaign Data Source. Either 2 (Pebble TV Playlist) or 3 (User/Custom Input). Default: 2
mediaIds
Array
Optional
An array of mediaId's (Only relevant when Ad Platform is 1 (Icareus Suite)
creativeId
Number
Optional
Icareus Suite Creative Identifier. Default: 0 (Only relevant when Ad Platform is 1 (Icareus Suite)
minShowTimePerDevice
Number
Optional
Minimum time between ad impressions on device (minutes). (Only relevant when Ad Platform is 1 (Icareus Suite)
maxShowsPerDay
Number
Optional
Maximum daily impressions per device. (Only relevant when Ad Platform is 1 (Icareus Suite)
maxWeeklyShowsPerDevice
Number
Optional
Maximum weekly impressions per device. (Only relevant when Ad Platform is 1 (Icareus Suite)
maxShowsPerCampaign
Number
Optional
Maximum Campaign Impressions. (Only relevant when Ad Platform is 1 (Icareus Suite)
campaignChannelStatusService
String
Optional
Channel Status Service URL. (Only if status service should be used).
campaignAdvertChannelStatus
String
Optional
Status on which Advert can be shown (Only if campaignChannelStatusService is provided). Either "COMMERCIAL" or "PROGRAM"
targeting
Object
Optional
See: Targeting Object
reconcileKeys
Array
Optional
Reconcile Keys Array.
adTagUrl
String
Optional (Mandatory if adPlatform = 2)
Ad Tag URL. Required when Ad Platform is 2 (AdForm).
adFormCreativeType
Number
Optional
AdForm Creative Type. See: Valid Creative Types. Default: 1  (Only relevant when Ad Platform is 2 (AdForm)

Example Switch In Data Object:
  1. {
      "name": "API SwitchIn Example",
      "channels": [
        56810,
        57067,
        57336,
        58810
      ],
      "adPlatform": 1,
      "dataSource": 2,
      "creativeId": 652315,
      "bannerVisibleTime": 15,
      "bannerInteractionTime": 10,
      "minShowTimePerDevice": 1,
      "maxShowsPerDevice": 1000,
      "maxWeeklyShowsPerDevice": 5000,
      "maxShowsPerCampaign": 10000,
      "cpmPrice": 0,
      "targeting": {
        "params": [
          {
            "name": "regionId",
            "value": "004"
          }
        ]
      }
    }


In-Stream Video Campaign Data

JSON Object expected when creating an In-Stream Video Campaign:

Key
Value
Requirement
Info
name
String
Mandatory
Name of the Campaign.
adProfileId
Number
Mandatory
Icareus Suite Ad Profile Identifier. (Must be of type: PREROLL or MIDROLL)
cpmPrice
Number
Mandatory
A number greater than or equal to 0.
channels
Array
Optional
An array of Icareus Suite Linear Channel Identifiers.

Example In-Stream Video Data Object:
  1. {
      "name": "API In-Stream Video Example",
      "channels": [
        56810,
        57067
      ],
      "adProfileId": 682288,
      "cpmPrice": 0
    }


In-Video Overlay Campaign Data

JSON Object expected when creating an In-Video Overlay Campaign:

Key
Value
Requirement
Info
name
String
Mandatory
Name of the Campaign.
adProfileId
Number
Mandatory
Icareus Suite Ad Profile Identifier. (Must be of type: OVERLAY)
cpmPrice
Number
Mandatory
A number greater than or equal to 0.
channels
Arrary
Optional
An array of Icareus Suite Linear Channel Identifiers.

Example In-Video Overlay Data Object:
  1. {
      "name": "API In-Video Overlay Example",
      "channels": [
        56810
      ],
      "adProfileId": 653101,
      "cpmPrice": 0
    }

Updating existing Campaigns

To edit an existing campaign, just include the "campaignId" -parameter to the add/edit Campaign API call. The type provided in the "type" -parameter needs to match the type of the Campaign you are editing.
Include only the keys/values that you wish to edit in the Data Object, values not provided will not be changed.
Certain values cannot be changed for an existing Campaign:
  1. adPlatform
  2. dataSource


Targeting Object

The expected format for the Campaign targeting object is as follows:
Key
Value
Requirement
Info
params
Array
Mandatory
An array containing Param Objects

Param Object

Key
Value
Requirement
Info
name
String
Mandatory
Expected value: "regionId"
value
String
Mandatory
The regionId as a String. i.e. "004"

An example of a Targeting Object:
  1. "targeting": {
      "params": [
        {
          "name": "regionId",
          "value": "004"
        }
      ]
    }

Add/Edit Campaign Schedule


Creates a new Schedule and attaches it to the specified Campaign. Or Edits an existing Schedule.

REQUEST

Method: POST
Parameters:

Name
Value
Requirement
Info
action
addUpdateCampaignSchedule
Mandatory

organizationId
Number
Mandatory
Icareus Suite Organization Identifier.
token
String
Mandatory
Secret key of the Organization.
userId
Number
Mandatory
Icareus Suite User Identifier. (Must be a Affiliate Administrator or Ismaccount Administrator)
campaignId
Number
Mandatory
Icareus Suite Campaign Identifier
scheduleId
Number
Optional
Icareus Suite Schedule Identiefer. If provided, an existing Schedule will be updated.
data
String
Optional
Encoded JSON Object containing the Schedule data.

NOTE: The JSON Object containing the data for the Schedule can either be provided through the 'data' -parameter as an encoded string. Or the JSON Object can be provided in the request body.

Schedule Data JSON Object

JSONObject expected when creating a new Schedule:
Key
Value
Requirement
Info
name
String
Mandatory
Name of the Schedule.
startDate
String/Date
Mandatory
The start date of the Schedule. Format: "yyyy-MM-dd'T'HH:mm" i.e. "2019-11-25T12:00"
duration
String
Mandatory
Duration for the Schedule. Format: "HH:mm" i.e. "08:00" - duration of 8 hours. MAX. "24:00"
timeZone
Number
Optional
UTC offset for startDate, positive or negative integer. i.e. 1 for UTC+1 or -1 for UTC-1.
repeatType
String
Optional
Repeat type for the schedule. One of: "never", "daily", "weekly", "monthly", "yearly". Default: "never"
endDate
String/Date
Optional
The end date of the Schedule. Format: "yyyy-MM-dd" i.e. "2019-12-24". Default value is 1 year from startDate.
dailyRepeatOptions
Object
Mandatory IF repeatType = daily
See: dailyRepeatOptions Object
weeklyRepeatOptions
Object
Mandatory IF repeatType = weekly
See: weeklyRepeatOptions Object
monthlyRepeatOptions
Object
Mandatory IF repeatType = monthly
See: monthlyRepeatOptions Object
yearlyRepeatOptions
Object
Mandatory IF repeatType = yearly
See: yearlyRepeatOptions Object

dailyRepeatOptions Object

Key
Value
Requirement
Info
repeatType
Number
Optional
Daily repeat type. Either: 0 (Recur every X day(s)), 1 (Every workday). Default: 0
repeatDays
Number
Mandatory IF repeatType = 0
Value for X in 'Recur every X days'. Default: 1.

weeklyRepeatOptions Object

Key
Value
Requirement
Info
repeatWeeks
Number
Optional
Value for X in 'Repeat every X weeks'.
weekDays
Array
Optional
Array of weekdays represented as integers the schedule should be active on. 1 (Sunday) - 7 (Saturday). i.e. [ 1, 7 ] for a Schedule that is active on Saturday and Sunday. Default: Empty array.


monthlyRepeatOptions Object

Key
Value
Requirement
Info
repeatType
Number
Optional
Monthly repeat type. Either: 0 (Day X of every N months) or 1 (The Xth <WEEKDAY> of every N months). Default: 0
repeatDayOfMonth
Number
Optional
X in 'Day X of every N months'. Default: 1. Only relevant when repeatType = 0.
repeatDayPosition
Number
Optional
X in 'The Xth <WEEKDAY> of every N months'. One of: -1 (Last), 1 (First), 2 (Second), 3 (Third), 4 (Fourth). Default: 1. Only relevant when repeatType = 1.
day
Number
Optional
<WEEKDAY> in 'The Xth <WEEKDAY> of every N months'. Weekday represented as an integer. 1 (Sunday) - 7 (Monday). Default: 1. Only relevant when repeatType = 1
repeatMonth
Number
Optional
N in 'Day X of every N months' or 'The Xth <WEEKDAY> of every N months'. Default: 1.

yearlyRepeatOptions Object

Key
Value
Requirement
Info
repeatType
Number
Optional
Yearly repeat type. Either: 0 (Every <MONTH> <DATE> of every X years) or 1 (The Nth <WEEKDAY> of <MONTH> of every X years). Default: 0
date
Number
Optional
<DATE> in 'Every <MONTH> <DATE> of every X years). Value between 1 and 31. Default: 1. Only relevant when repeatType = 0
repeatDayPosition
Number
Optional
N in 'The Nth <WEEKDAY> of <MONTH> of every X years'. One of: -1 (Last), 1 (First), 2 (Second), 3 (Third), 4 (Fourth). Default: 1. Only relevant when repeatType = 1
day
Number
Optional
<WEEKDAY> in 'The Nth <WEEKDAY> of <MONTH> of every X years'. Weekday represented as an integer. 1 (Sunday) - 7 (Monday). Default: 1. Only relevant when repeatType = 1
month
Number
Optionial
<MONTH> in 'Every <MONTH> <DATE> of every X years' or 'The Nth <WEEKDAY> of <MONTH> of every X years'. Default: 1
repeatYear
Number
Optional
X in 'Every <MONTH> <DATE> of every X years' or 'The Nth <WEEKDAY> of <MONTH> of every X years'. Default: 1

Add/Edit Campaign Daily Caps

Adds new Daily Caps and attaches it to the specified Campaign. Or Edits existing Daily Caps.

REQUEST

Method: POST
Parameters:

Name
Value
Requirement
Info
action
addUpdateCampaignDailyCaps
Mandatory

organizationId
Number
Mandatory
Icareus Suite Organization Identifier.
token
String
Mandatory
Secret key of the Organization.
userId
Number
Mandatory
Icareus Suite User Identifier. (Must be a Affiliate Administrator or Ismaccount Administrator)
campaignId
Number
Mandatory
Icareus Suite Campaign Identifier
data
String
Optional
Encoded JSON Array containing the Daily Caps data.

NOTE: The JSON Object containing the data for the Schedule can either be provided through the 'data' -parameter as an encoded string. Or the JSON Object can be provided in the request body.

Daily Caps Data JSON Array

JSON Array expected for daily Caps, containing JSON Objects as below:
Key
Value
Requirement
Info
day
String/Date
Mandatory
The day of the. Format: "yyyy-MM-dd" i.e. "2023-12-08"
cap
Number
Mandatory
The cap number for that day, e.g. 1000

Example with cURL:

  1. curl -X POST 'https://suiterc.icareus.com/api/campaign/v5?action=addUpdateCampaignDailyCaps&organizationId=123345&token=ABCDE&userId=99999&campaignId=11111' -H 'Content-Type: application/json' -d '[{"day":"2023-12-04","cap":"2000"},{"day":"2023-12-05","cap":"3000"},{"day":"2023-12-06","cap":"4000"}]'

API PATH

/api/campaign/v5

API CALLS

Get Active Campaigns

Get the active campaigns that are scheduled for an organization. Optionally returns only campaigns of specific types.

REQUEST

Method: GET
Parameters:

Name
Value
Requirement
Info
action
getActiveCampaigns
Mandatory

organizationId
Number
Mandatory
Icareus Suite Organization Identifier.
campaignType
String
 Optional
If this parameter  (a comma separated list) is present in the request, only campaigns of of those types are returned in the response. Valid campaign types include: switchIn, inStreamVideo, inVideoOverlay, activead and videoswap.


    • Related Articles

    • Introduction to Addressable TV

      INTRODUCTION Icareus Suite enables broadcasters to maximise their revenue with Addressable TV formats. Icareus Suite in collaboration with Icareus Playout can be used to trigger and synchronise Display Ads and replace the broadcasted commercials with ...

    • Applications API (ENG)

      INTRODUCTION This API is used to manage Applications. You can create new Applications, edit existing Applications and upload new images for existing Applications. Currently only creation/editing of HbbTV Coupon Applications is supported! API PATH ...

    • Creatives API (ENG)

      INTRODUCTION This API is used to manage Creatives. You can create new Creatives, edit existing Creatives and upload new images for existing Creatives. API PATH /api/creatives API CALLS Add Creative Creates a new Creative. This call takes meta-data ...

    • Managing AddressableTV Campaigns

      Introduction Addressable TV Ad formats that are run on broadcast networks require configuration on both Icareus Suite (campaigns, creatives, integrations, ...) and Icareus Playout (HbbTV signalling, broadcast synchronization, etc). Requirements for ...

    • Analytics API (ENG)

      INTRODUCTION This API stores video access/usage statistics for the linear channels and vod items. API PATH /api/analytics API METHODS ADDING NEW RECORD Adds a new analytics record of either on-demand video usage or linear channel viewing statistics ...