Campaign API

Use the Campaign API to define some general settings for the campaign. Give the campaign a name, associate it with a client, set the campaign priority, delivery mode and targeting rules.

Getting Started

  • Base URL: https://api.videoplaza.com/api/1.0/campaign.
  • Requests: GET, POST, PUT, and DELETE requests are used. You pass parameters by using common REST parameters like PATH, QUERY, and MATRIX, as well as HTTP HEADERS. The body of the requests should be provided in XML format and encoded using UTF-8.
  • Responses: All responses contain an HTTP status code in the header and the body is in XML format.
  • Related user documentation:

Request Body Format

To create and update campaigns, you need to supply a body to the request with the following format:
Note: Only the name parameter is required. All other parameters are optional.
<campaignBean>
    <advertiserId>string</advertiserId>
    <agencyId>string</agencyId>
    <brandId>string</brandId>
    <budget>
        <value>number</value>
    </budget>
     <!-- <cpmHigh> (Setting this value is ignored)
        <value>number</value>
    </cpmHigh> -->
   <!-- <cpmLow> (Setting this value is ignored) 
        <value>number</value>
    </cpmLow> -->
    <customId>string</customId>
    <description>string</description>
    <enabled>boolean</enabled>    <!-- (Defaults to false) -->
    <!-- <end>2016-10-26T08:36:28</end> (Setting this value is ignored) -->
    <exclusive>boolean</exclusive>    <!-- (Defaults to false) -->
    <frontLoadFactor>0|10|20|30|40|50|60|70|80|90|100</frontLoadFactor>    <!-- (Defaults to match the global frontload setting) -->
    <goalTotal>number</goalTotal>
    <goalType>IMPRESSION|MIXED|SHARE_OF_VOICE</goalType>
    <id>string</id>    <!-- (Set only when updating a campaign) -->
    <includeInForecast>boolean</includeInForecast>    <!-- (Defaults to true) -->
    <name>string</name>    <!-- (Required) -->
    <priority>integer</priority>    <!-- (1-10; defaults to match the global priority setting) -->
    <!-- <start>2016-10-01T06:36:46+01:00</start> (Setting this value is ignored) -->
    <status>ACTIVE|RECENT|UPCOMING|ARCHIVED</status>    <!-- (The only valid value that can be set is ARCHIVED) -->
    <vastEnabled>boolean</vastEnabled>    <!-- (Defaults to false) -->
</campaignBean>

Create a Campaign

Method POST
URL https://api.videoplaza.com/api/1.0/campaign
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params -
Query params -
Body Request Body Format
Success response

HTTP status: 200 OK

Header: -

Body: campaign ID

Example:

Request header:

POST /api/1.0/campaign HTTP/1.1
Host: api.videoplaza.com
Content-type: application/xml
x-o-api-key="<your key>"

Request body:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <campaignBean>
        <advertiserId>f16dd041-a659-4f7f-bf53-b7f1fcd84bee</advertiserId>       
        <description>API test campaign.</description>
        <enabled>true</enabled>
        <exclusive>false</exclusive>
        <frontLoadFactor>20</frontLoadFactor>              
        <includeInForecast>false</includeInForecast>
        <name>API campaign</name>
        <priority>4</priority>        
        <vastEnabled>true</vastEnabled>
    </campaignBean>

Success response:

HTTP status:
  200 (OK)

Body:
84a19c28-­ba66-­411b-­a5bf-­49ecfce1e607

Update a Campaign

Method PUT
URL https://api.videoplaza.com/api/1.0/campaign/by_campaign_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: campaign ID
Query params -
Body Request Body Format
Success response

HTTP status: 204 No Content

Header: -

Body: -

Example:

Request header:

PUT /api/1.0/campaign/by_campaign_id;id=84a19c28-­ba66-­411b-­a5bf-­49ecfce1e607 HTTP/1.1
Host: api.videoplaza.com
Content-­type: application/xml
x-o-api-key="<your key>"

Request body:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<campaignBean>
        <advertiserId>f16dd041-a659-4f7f-bf53-b7f1fcd84bee</advertiserId>
        <agencyId>3f01fedc-06fe-442e-a185-0a8e6433cd96</agencyId>
        <brandId>0d1d3dfb-359a-4ab9-bcf9-fb555b5accd9</brandId>
        <description>API test campaign.</description>
        <enabled>true</enabled>
        <exclusive>false</exclusive>
        <frontLoadFactor>40</frontLoadFactor>
        <id>84a19c28-­ba66-­411b-­a5bf-­49ecfce1e607</id>
        <includeInForecast>true</includeInForecast>
        <name>API Test Campaign</name>
        <priority>10</priority>        
        <vastEnabled>true</vastEnabled>
    </campaignBean>

Success response:

HTTP status:
  204 (No Content)

Delete a Campaign

Method DELETE
URL https://api.videoplaza.com/api/1.0/campaign/by_campaign_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: campaign ID
Query params -
Body -
Success response

HTTP status: 204 No Content

Header: -

Body: -

Example:

Request header:

DELETE /api/1.0/campaign/by_campaign_id;id=84a19c28-­bb66-­411b-­a5bf-­49efgfce1e607 HTTP/1.1
Host: api.videoplaza.com
Content-type: application/xml
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  204 (No Content)

List Campaigns

Method GET
URL https://api.videoplaza.com/api/1.0/campaign
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params -
Query params Optional; Filter campaigns based on their status and/or state :
  1. status:
    • active
    • recent
    • upcoming
  2. state:
    • archived
    • disabled
    • enabled
Body -
Success response

HTTP status: 200 OK

Header: -

Body: list of campaigns

Example:

Request header:

GET /api/1.0/campaign?status=upcoming&state=enabled HTTP/1.1
Host: api.videoplaza.com
Content-type: application/xml
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  200 (OK)

Body:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<collection>
    <campaignBean>
        <advertiserId>20020002-f299-489a-a9e1-362bfbe0c676</advertiserId>
        <enabled>true</enabled>
        <exclusive>false</exclusive>
        <frontLoadFactor>0</frontLoadFactor>
        <goalTotal>0.0</goalTotal>
        <id>c3abb649-e45f-4692-a467-083e9968af6b</id>
        <includeInForecast>true</includeInForecast>
        <name>Royco_2016_10</name>
        <priority>5</priority>
        <status>UPCOMING</status>
        <vastEnabled>true</vastEnabled>
    </campaignBean>
    <campaignBean>
        <advertiserId>664e3f55-3b89-4e2d-8635-5421716a00f7</advertiserId>
        <enabled>true</enabled>
        <exclusive>false</exclusive>
        <goalTotal>0.0</goalTotal>
        <id>f007aced-330c-4961-9da2-31527458bee5</id>
        <includeInForecast>true</includeInForecast>
        <name>Coca cola</name>
        <status>UPCOMING</status>
        <vastEnabled>true</vastEnabled>
    </campaignBean>
</collection>

List Archived Campaigns

Method GET
URL https://api.videoplaza.com/api/1.0/campaign/archived
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params -
Query params Filter archived campaigns based on year and month the campaigns were running:
  1. year: 4 digit integer (for example, 2017)
  2. month: integer, 1-12
    • 1 (January)
    • 2 (February)
    • 3 (March), and so on.
Note: If no year or month is specified, you get a list of archived campaigns for current year and month.
Body -
Success response

HTTP status: 200 OK

Header: -

Body: list of campaigns

Example:

Request header:

GET /api/1.0/campaign/archived?year=2016&month=8 HTTP/1.1
Host: api.videoplaza.com
Content-type: application/xml
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  200 (OK)

Body:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<collection>
    <campaignBean>
        <advertiserId>f16dd041-a659-4f7f-bf53-b7f1fcd84bee</advertiserId>
        <cpmHigh>
            <value>4.9E-324</value>
        </cpmHigh>
        <cpmLow>
            <value>0.0</value>
        </cpmLow>
        <enabled>false</enabled>
        <end>2016-08-21T13:16:32+0200</end>
        <exclusive>false</exclusive>
        <goalTotal>250000.0</goalTotal>
        <goalType>IMPRESSION</goalType>
        <id>49428852-473d-4be8-a142-7abd85b7d9aa</id>
        <includeInForecast>true</includeInForecast>
        <name>IKEA_Sverige</name>
        <priority>5</priority>
        <start>2016-07-04T14:16:32+0200</start>
        <status>ARCHIVED</status>
        <vastEnabled>true</vastEnabled>
    </campaignBean>
    <campaignBean>
        <advertiserId>20020002-f299-489a-a9e1-362bfbe0c676</advertiserId>
        <agencyId>c9c72b46-4464-4ca8-aad4-6080b66f3318</agencyId>
        <brandId>d01b019f-0115-4384-a218-6b80c1bb803a</brandId>
        <cpmHigh>
            <value>4.9E-324</value>
        </cpmHigh>
        <cpmLow>
            <value>0.0</value>
        </cpmLow>
        <enabled>false</enabled>
        <end>2016-08-25T14:16:00+0200</end>
        <exclusive>false</exclusive>
        <goalTotal>74000.0</goalTotal>
        <goalType>IMPRESSION</goalType>
        <id>ce0e6dc2-feed-4711-96d2-1cb4992fd0cf</id>
        <includeInForecast>true</includeInForecast>
        <name>Royco_201607</name>
        <priority>2</priority>
        <start>2016-07-04T14:16:21+0200</start>
        <status>ARCHIVED</status>
        <vastEnabled>true</vastEnabled>
    </campaignBean>
    <campaignBean>
        <advertiserId>9692f005-7d78-4ec2-ba0c-0e6bff86c5ae</advertiserId>
        <cpmHigh>
            <value>4.9E-324</value>
        </cpmHigh>
        <cpmLow>
            <value>0.0</value>
        </cpmLow>
        <enabled>false</enabled>
        <end>2016-08-14T02:42:00+0200</end>
        <exclusive>false</exclusive>
        <goalTotal>52000.0</goalTotal>
        <goalType>IMPRESSION</goalType>
        <id>d1b89e0c-9528-4c1c-b233-ecaab0c99b82</id>
        <includeInForecast>true</includeInForecast>
        <name>Argos_storytelling_2016</name>
        <priority>3</priority>
        <start>2016-07-07T03:42:00+0200</start>
        <status>ARCHIVED</status>
        <vastEnabled>true</vastEnabled>
    </campaignBean>
</collection>

List Campaign(s) by ID

Method GET
URL https://api.videoplaza.com/api/1.0/campaign/by_campaign_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: campaign ID
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: list of campaigns

Example:

Request header:

GET /api/1.0/campaign/by_campaign_id;id=f007aced-330c-4961-9da2-31527458bee5 HTTP/1.1
Host: api.videoplaza.com
Content-type: application/xml
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  200 (OK)

Body:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<collection>
    <campaignBean>
        <advertiserId>664e3f55-3b89-4e2d-8635-5421716a00f7</advertiserId>
        <enabled>true</enabled>
        <exclusive>false</exclusive>
        <goalTotal>0.0</goalTotal>
        <id>f007aced-330c-4961-9da2-31527458bee5</id>
        <includeInForecast>true</includeInForecast>
        <name>Coca cola</name>
        <status>UPCOMING</status>
        <vastEnabled>true</vastEnabled>
    </campaignBean>
</collection>

List Notifications by Campaign ID

Method GET
URL https://api.videoplaza.com/api/1.0/campaign/notification/by_campaign_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: campaign ID
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: map (key campaign id, value list of notifications)

Example:

Request header:

GET /api/1.0/campaign/notification/by_campaign_id;id=b67fd507-8e80-41f6-bdc2-3af60f058b7e HTTP/1.1
Host: api.videoplaza.com
Content-type: application/xml
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  200 (OK)

Body:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<map>
    <entry key="b67fd507-8e80-41f6-bdc2-3af60f058b7e">
        <notificationList>
            <notificationBeans>
                <concernedResource>
                    <id>59a0fc5f-d22b-40a2-ac72-264663c84c7e</id>
                    <type>GOAL</type>
                </concernedResource>
                <level>WARNING</level>
                <message>Running goal is missing active ads during some of its run time. (Royco_201607)</message>
                <relatedResources>
                    <id>b67fd507-8e80-41f6-bdc2-3af60f058b7e</id>
                    <type>CAMPAIGN</type>
                </relatedResources>
            </notificationBeans>
        </notificationList>
    </entry>
</map>

Retrieve Campaign Rules

Method GET
URL https://api.videoplaza.com/api/1.0/campaign/rule/by_campaign_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: campaign ID
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: rulesBean

Example:

Request header:

GET /api/1.0/campaign/rule/by_campaign_id;id=c3abb649-e45f-4692-a467-083e9968af6b HTTP/1.1
Host: api.videoplaza.com
Content-­type: application/xml
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  200 (OK)

Body:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rulesBean>
    <frequencyCappings>
        <impressions>2</impressions>
        <timeUnit>DAY</timeUnit>
    </frequencyCappings>
    <ignoreParentContentRules>false</ignoreParentContentRules>
    <ignoreParentFrequencyRules>false</ignoreParentFrequencyRules>
    <ignoreParentLocationRules>false</ignoreParentLocationRules>
    <ignoreParentTagRules>false</ignoreParentTagRules>
    <ignoreParentTimeRules>false</ignoreParentTimeRules>
    <locations>
        <allowed>true</allowed>
        <country>norway</country>
        <id>578</id>
        <iso2>no</iso2>
        <locationType>COUNTRY</locationType>
    </locations>
    <locations>
        <allowed>true</allowed>
        <country>sweden</country>
        <id>752</id>
        <iso2>se</iso2>
        <locationType>COUNTRY</locationType>
    </locations>
    <parentId>c3abb649-e45f-4692-a467-083e9968af6b</parentId>
    <tags>
        <resourceId>violence</resourceId>
        <resourceName>violence</resourceName>
        <ruleType>NONE_OF</ruleType>
        <variableType>TAG</variableType>
    </tags>
    <timeRestrictions>
        <active>true</active>
        <days>SUNDAY</days>
        <days>SATURDAY</days>
        <fromHour>0</fromHour>
        <fromMinute>0</fromMinute>
        <toHour>23</toHour>
        <toMinute>59</toMinute>
    </timeRestrictions>
</rulesBean>

Update Campaign Rules

To update campaign rules, you need to supply a body to the request with the following format:

<rulesBean>
    <parentId>string</parentId>    <!-- Campaign id -->
    <content>
        <resourceId>string</resourceId>    <!-- Category id/Content Partner id/Tag value -->
        <!-- <resourceName>string</resourceName> (Category/Content Partner/Tag name; setting this value is ignored) -->
        <ruleType>ALL_OF|AT_LEAST_ONE_OF|NONE_OF</ruleType>
        <variableType>CONTENT_PARTNER|SITE|TAG</variableType>
    </content>
    <frequencyCappings>
        <impressions>integer</impressions>    <!-- Number of impressions to allow in this time period -->
        <timeUnit>HOUR|DAY|WEEK|MONTH</timeUnit>
    </frequencyCappings>
    <locations>
        <allowed>boolean</allowed>
        <!-- <country>string</country> (Name of the country; setting this value is ignored) -->
        <id>string</id>
        <iso2>string</iso2>
        <locationType>COUNTRY</locationType>
    </locations>
    <locations>
        <allowed>boolean</allowed>
        <!-- <region>string</region> (Name of the region; setting this value is ignored) -->
        <id>string</id>
        <iso2>string</iso2>
        <locationType>REGION</locationType>
    </locations>
    <locations>
        <allowed>boolean</allowed>
        <!-- <city>string</city> (Name of the city; setting this value is ignored) -->
        <id>string</id>    <!-- Location id -->
        <iso2>string</iso2>
        <locationType>CITY</locationType>
    </locations>
    <timeRestrictions>    <!-- Time restrictions should be specified in the site's time zone -->
        <active>boolean</active>
        <days>MONDAY|TUESDAY|WEDNESDAY|THURSDAY|FRIDAY|SATURDAY|SUNDAY</days>        
        <fromHour>0-23</fromHour>
        <fromMinute>0-59</fromMinute>
        <toHour>0-23</toHour>
        <toMinute>0-59</toMinute>
    </timeRestrictions>
    <tags>
        <resourceId>string</resourceId>    <!-- Category id/Content Partner id/Tag value -->
        <!-- <resourceName>string</resourceName> (Category/Content Partner/Tag name; setting this value is ignored) -->
        <ruleType>ALL_OF|AT_LEAST_ONE_OF|NONE_OF</ruleType>
        <variableType>CONTENT_PARTNER|SITE|TAG</variableType>
    </tags>
    <ignoreParentContentRules>boolean</ignoreParentContentRules>
    <ignoreParentFrequencyRules>boolean</ignoreParentFrequencyRules>
    <ignoreParentLocationRules>boolean</ignoreParentLocationRules>
    <ignoreParentTagRules>boolean</ignoreParentTagRules>
    <ignoreParentTimeRules>boolean</ignoreParentTimeRules>
</rulesBean>
The ignoreParentRules parameters can be set to:
  • true: override global targeting rules, meaning the campaign applies its own targeting rules.
  • false: no targeting rules override, meaning the campaign rules are merged with the parent rules.
For more information on targeting rules, refer to Targeting Rules Overview.
Note: Capping the maximum number of impressions per 15 minutes, 30 minutes, and campaign lifetime is not supported through the API.
Method PUT
URL https://api.videoplaza.com/api/1.0/campaign/rules/by_campaign_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: campaign ID
Query params -
Body Request Body Format
Success response

HTTP status: 204 No Content

Header: -

Body: -

Example:

Request header:

PUT /api/1.0/campaign/rules/by_campaign_id;id=c3abb649-e45f-4692-a467-083e9968af6b HTTP/1.1
Host: api.videoplaza.com
Content-­type: application/xml
x-o-api-key="<your key>"

Request body:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rulesBean>
    <parentId>c3abb649-e45f-4692-a467-083e9968af6b</parentId>
    <content>
        <resourceId>dc74b090-c275-4646-a37f-4d5cff09997a</resourceId>
        <resourceName>Entertainment</resourceName>
        <ruleType>AT_LEAST_ONE_OF</ruleType>
        <variableType>SITE</variableType>
    </content>
    <content>
        <resourceId>df5480fd-ca38-43c8-a44c-4240965e2023</resourceId>
        <resourceName>Sport</resourceName>
        <ruleType>AT_LEAST_ONE_OF</ruleType>
        <variableType>SITE</variableType>
    </content>
    <frequencyCappings>
        <impressions>2</impressions>
        <timeUnit>DAY</timeUnit>
    </frequencyCappings>
    <locations>
        <allowed>true</allowed>
        <country>norway</country>
        <id>578</id>
        <iso2>no</iso2>
        <locationType>COUNTRY</locationType>
    </locations>
    <locations>
        <allowed>true</allowed>
        <country>sweden</country>
        <id>752</id>
        <iso2>se</iso2>
        <locationType>COUNTRY</locationType>
    </locations>
    <locations>
        <allowed>false</allowed>
        <country>iceland</country>
        <id>352</id>
        <iso2>is</iso2>
        <locationType>COUNTRY</locationType>
    </locations>
    <timeRestrictions>
        <active>true</active>
        <days>SUNDAY</days>
        <days>SATURDAY</days>
        <fromHour>0</fromHour>
        <fromMinute>0</fromMinute>
        <toHour>23</toHour>
        <toMinute>59</toMinute>
    </timeRestrictions>
    <tags>
        <resourceId>violence</resourceId>
        <resourceName>violence</resourceName>
        <ruleType>NONE_OF</ruleType>
        <variableType>TAG</variableType>
    </tags>
    <ignoreParentContentRules>true</ignoreParentContentRules>
    <ignoreParentFrequencyRules>true</ignoreParentFrequencyRules>
    <ignoreParentLocationRules>true</ignoreParentLocationRules>
    <ignoreParentTagRules>true</ignoreParentTagRules>
    <ignoreParentTimeRules>true</ignoreParentTimeRules>   
</rulesBean>

Success response:

HTTP status:
  204 (No Content)

해당 내용이 도움 되었습니까?