Creatives API (ENG)

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 only. Once a Creative has been successfully created, images can be uploaded to it using the addImages action.

REQUEST

Method: POST
Parameters:
Name
Value
Requirement
Info
action
addUpdateCreative
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)
creativeName
String
Mandatory
Name of the Creative being created
creativeType
Number
Mandatory
Type of the Creative being created
targetType
Number
Mandatory
Activation Type of the Creative being created. (1: Suite Application, 2: External URL)
targetApplicationId
Number
Mandatory when targetType is 1
Icareus Suite HbbTV Application Identifier.
externalUrl
String
Mandatory when targetType is 2

Creative Types:

Number
Creative Type
1
L-Banner Bottom-left
2
L-Banner Bottom-right
3
L-Banner Top-right
4
L-Banner Top-left
5
Leaderboard
6
Medium Rectangle (Right)
7
Medium Rectangle (Left)
8
Stripe (Bottom)


RESPONSE (SUCCESS):

  1. {
    "creativeId": 872423,
    "status": "ok",
    "data": {
    "image3Id": 0,
    "targetData": {
    "applicationId": 865563
    },
    "creativeId": 872423,
    "image2Id": 0,
    "name": "Test Creative",
    "image4Id": 0,
    "image1Id": 0,
    "type": 6,
    "targetType": 1
    }
    }

RESPONSE (ERROR):

  1. {
    "message": "Invalid User Id.",
    "status": "error"
    }
Same pattern applies to all acknowledgement calls. Status "ok" means a successful execution of the intended action. Status "error" will have the corresponding error information in the message parameter.

Update Creative


Update an existing Creative. This call can only be used to update meta-data. Images can be updated using the addImages action.

REQUEST

Method: POST
Parameters:
Name
Value
Requirement
Info
action
addUpdateCreative
Mandatory

creativeId
Number
Mandatory
Icareus Suite Creative Identifier of the Creative being updated
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)
creativeName
String
Optional
New name for the Creative being updated
creativeType
Number
Optional
New Type for the Creative being updated
targetType
Number
Optional
Activation Type of the Creative being updated. (1: Suite Application, 2: External URL)
targetApplicationiId
Number
Mandatory IF changing the targetType from 2 to 1
Icareus Suite HbbTV Application Identifier
externalUrl
String
Mandatory IF changing the targetType from 1 to 2

RESPONSE (SUCCESS):

  1. {
    "creativeId": 872423,
    "status": "ok",
    "data": {
    "image3Id": 0,
    "targetData": {
    },
    "creativeId": 872423,
    "image2Id": 0,
    "name": "Test Creative Update",
    "image4Id": 0,
    "image1Id": 0,
    "type": 6,
    "targetType": 2
    }
    }

RESPONSE (ERROR):

  1. {
    "message": "Invalid targetType.",
    "status": "error"
    }
Same pattern applies to all acknowledgement calls. Status "ok" means a successful execution of the intended action. Status "error" will have the corresponding error information in the message parameter.

Add / Update Images


Add / Update the images of a specified Creative. Below is a table defining what image(s) each Creative type is expected to have.
Creative Type Identifier
Creative Type Name
Expected Images
1
L-Banner (Bottom Left)
image1, image2
2
L-Banner (Bottom Right)
image1, image2
3
L-Banner (Top Right)
image1, image2
4
L-Banner (Top Left)
image1, image2
5
Leaderboard
image1
6
Medium Rectangle (Right)
image1
7
Medium Rectangle (Left)
image1
8
Stripe (Bottom)
image1

REQUEST

Method: POST
Parameters:
Name
Value
Requirement
Info
action
addUpdateImages
Mandatory

creativeId
Number
Mandatory
Icareus Suite Creative Identifier of the Creative being updated
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)
image1
File
Optional*
Image to be added to the Creative
image2
File
Optional*
Image to be added to the Creative
* At least one of the expected images need to be supplied for the given Creative Type from the table above. Otherwise an error response will be returned as there is no suitable images to update.

RESPONSE (SUCCESS):

  1. {
    "creativeId": 872423,
    "status": "ok",
    "data": {
    "image3Id": 0,
    "targetData": {
    },
    "creativeId": 872423,
    "image2Id": 0,
    "name": "Test Creative Update",
    "image4Id": 0,
    "image1Id": 872425,
    "type": 6,
    "targetType": 2
    }
    }

RESPONSE (ERROR):

  1. {
    "message": "Expected to find image for 'image1'.",
    "status": "error"
    }
    • 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 ...
    • 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 ...
    • 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 ...
    • 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 ...
    • VideoSwap Format and Configuration

      Introduction VideoSwap format is Icareus' solution for Dynamic Ad insertion or substitution (DAS). It enables substitution of linear TV spots or pods with more personalised video ads. Supported platforms HbbTV OTT Browser based set-top box ...