Goal

The Goal endpoints allow you to create, update, delete, and list campaign goals. This can be done in two different ways, depending on whether you are using only share of voice, impression, and unlimited impression goals, or you are also using % ad completion (CPV or cost-per-view model) and click-through (CPC or cost-per-click model) goals.

Important:
  • Use the https://api.videoplaza.com/api/1.0/goal endpoint if you are using only share of voice, impression, and unlimited impression goals.
  • Use the https://api.videoplaza.com/api/1.0.cpvext/goal endpoint if you are using all existing goal types.
To create or update a share of voice, impression, or unlimited impression goal, using the https://api.videoplaza.com/api/1.0/goal endpoint, you need to supply a body to the request with the following format:
Note: All parameters are optional unless explicitly stated.
<goalBean>
    <budget>
        <value>number</value>   
    </budget>
    <campaignId>string</campaignId>    <!-- Required -->
    <!-- <cpm> (Setting this value is ignored)
        <value>number</value>
    </cpm> -->
    <customId>string</customId>
    <description>string</description>
    <end>2016-09-29T03:49:45</end>
    <formatType>PREROLL|MIDROLL|POSTROLL|OVERLAY|COMPANION_BANNER|INSKIN|SPLASH|SEEKROLL|PAUSE_AD</formatType>    <!-- Defaults to PREROLL -->
    <frontLoadFactor>0|10|20|30|40|50|60|70|80|90|100</frontLoadFactor>    <!-- Defaults to match the global frontload setting or the campaign frontload setting if it overrides the global one -->
    <goalValue>number</goalValue>    <!-- Required; see below for more information -->
    <id>string</id>    <!-- This should only be set when updating a goal -->
    <name>string</name>
    <priority>integer</priority>    <!-- 1-10; defaults to match the global priority setting or the campaign priority setting if it overrides the global one -->
    <start>2016-09-01T19:44:14</start>    <!-- Required -->
    <type>SHARE_OF_VOICE|IMPRESSION|UNLIMITED_IMPRESSION</type>    <!-- Required -->
    <unlimitedImpressions>boolean</unlimitedImpressions>
    <variant>NORMAL|BUMPER</variant>    <!-- Required, "bumper" corresponds to sponsor goal mode in the Pulse UI --> 
</goalBean>
Setting the goalValue parameter for unlimited impression goals is ignored. Valid values for goal types:
  • Share of voice goals: 0.01-1.0
  • Impression goals: any positive number
To create or update all existing goal types using the https://api.videoplaza.com/api/1.0.cpvext/goal endpoint, you need to supply a body to the request with the following format:
Note: All parameters are optional unless explicitly stated.
<goalBean>
    <pricingModel>NO_PRICING|BUDGET|CPM|CPMV_25|CPMV_50|CPMV_75|CPMV_100|CPC</pricingModel>    <!-- See below for more information -->
    <pricingValue>
            <value>number</value>
        </pricingValue>
    <campaignId>string</campaignId>    <!-- Required -->
    <!-- <cpm> (Setting this value is ignored)
        <value>number</value>
    </cpm> -->
    <customId>string</customId>
    <description>string</description>
    <end>2016-09-29T03:49:45</end>
    <formatType>PREROLL|MIDROLL|POSTROLL|OVERLAY|COMPANION_BANNER|INSKIN|SPLASH|SEEKROLL|PAUSE_AD</formatType>    <!-- Defaults to PREROLL -->
    <frontLoadFactor>0|10|20|30|40|50|60|70|80|90|100</frontLoadFactor>    <!-- Defaults to match the global frontload setting or the campaign frontload setting if it overrides the global one -->
    <goalValue>number</goalValue>    <!-- Required; see note below for more information -->
    <id>string</id>    <!-- This should only be set when updating a goal -->
    <name>string</name>
    <priority>integer</priority>    <!-- 1-10; defaults to match the global priority setting or the campaign priority setting if it overrides the global one -->
    <start>2016-09-01T19:44:14</start>    <!-- Required -->
    <type>SHARE_OF_VOICE|IMPRESSION|UNLIMITED_IMPRESSION|FIRST_QUARTILE|SECOND_QUARTILE|THIRD_QUARTILE|COMPLETE|CLICK_THROUGH</type>    <!-- Required; see below for more information -->
    <unlimitedImpressions>boolean</unlimitedImpressions>
    <variant>NORMAL|BUMPER</variant>    <!-- Required, "bumper" corresponds to sponsor goal mode in the Pulse UI --> 
</goalBean>
  1. The pricing models CPMV_25, CPMV_50, CPMV_75, and CPMV_100 correspond to the following Pulse UI pricing options:
    • CPMV_25: CPM 25% Ad Completion
    • CPMV_50: CPM 50% Ad Completion
    • CPMV_75: CPM 75% Ad Completion
    • CPMV_100: CPM 100% Ad Completion
  2. The types FIRST_QUARTILE, SECOND_QUARTILE, THIRD_QUARTILE, and COMPLETE correspond to the following Pulse UI goal types:
    • FIRST_QUARTILE: 25% Ad Completion
    • SECOND_QUARTILE: 50% Ad Completion
    • THIRD_QUARTILE: 75% Ad Completion
    • COMPLETE: 100% Ad Completion

Create a Goal

Method POST
URI path /api/1.0/goal
Matrix params -
Query params -
Content type application/xml
XML Body goalBean
   
Returns goal id

Example:

Request header:

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

Request body:

<goalBean>     
        <campaignId>c3abb649-e45f-4692-a467-083e9968af6b</campaignId>
        <end>2016-10-30T00:00:00+0200</end>       
        <goalValue>30000.0</goalValue>        
        <name>Royco Midroll</name>
        <start>2016-09-30T00:00:00+0200</start>
        <type>IMPRESSION</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>

Success response:

HTTP status:
  200 (OK)

Body:
8e81973f-51f3-4769-9627-885546d7c450
Method POST
URI path api/1.0.cpvext/goal
Matrix params -
Query params -
Content type application/xml
XML Body goalBean
   
Returns goal id

Example:

Request header:

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

Request body:

<goalBean>
        <campaignId>135ae70d-0e70-4d52-a71b-f9d95745fc74</campaignId>
        <end>2017-05-24T00:00:00+02:00</end>
        <formatType>PREROLL</formatType>
        <goalValue>12000.0</goalValue>
        <id>b4c6e094-4ef5-4aac-949a-d9377af7abf4</id>
        <name>Royco Preroll</name>
        <pricingModel>CPMV_50</pricingModel>
        <pricingValue>
            <value>15.0</value>
        </pricingValue>
        <start>2017-04-24T10:16:54.762+02:00</start>
        <type>SECOND_QUARTILE</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>

Success response:

HTTP status:
  200 (OK)

Body:
eece5f87-f34e-41f0-921e-dbd44bbf3280

Update a Goal

Method PUT
URI path api/1.0/goal/by_goal_id
Matrix params id [1]
Query params -
Content type application/xml
XML Body goalBean
   
Returns -

Example:

Request header:

PUT /api/1.0/goal/by_goal_id;id=8e81973f-51f3-4769-9627-885546d7c450 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"?>
    <goalBean>
        <customId>My custom goal ID.</customId>
        <campaignId>c3abb649-e45f-4692-a467-083e9968af6b</campaignId>        
        <description>Changed the description for the impression goal through API.</description>
        <end>2016-10-30T00:00:00+0200</end>
        <formatType>MIDROLL</formatType>
        <frontLoadFactor>40</frontLoadFactor>
        <goalValue>50000.0</goalValue>
        <id>8e81973f-51f3-4769-9627-885546d7c450</id>
        <name>Royco Midroll</name>
        <priority>6</priority>
        <start>2016-09-30T00:00:00+0200</start>
        <type>IMPRESSION</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>

Success response:

HTTP status:
  204 (No Content)
Method PUT
URI path api/1.0.cpvext/goal/by_goal_id
Matrix params id [1]
Query params -
Content type application/xml
XML Body goalBean
   
Returns -

Example:

Request header:

PUT /api/1.0.cpvext/goal/by_goal_id;id=eece5f87-f34e-41f0-921e-dbd44bbf3280 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"?>
    <goalBean>
        <customId>My custom goal ID.</customId>
        <campaignId>135ae70d-0e70-4d52-a71b-f9d95745fc74</campaignId>        
        <description>Changed the description for the 50% ad completion goal through API.</description>
        <end>2017-05-24T00:00:00+02:00</end>
        <formatType>PREROLL</formatType>
        <frontLoadFactor>40</frontLoadFactor>
        <goalValue>12000.0</goalValue>
        <id>eece5f87-f34e-41f0-921e-dbd44bbf3280</id>
        <name>Royco Preroll</name>
        <pricingModel>CPMV_50</pricingModel>
        <pricingValue>
            <value>15.0</value>
        </pricingValue>
        <priority>6</priority>
        <start>2017-04-24T10:16:54.762+02:00</start>
        <type>SECOND_QUARTILE</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>

Success response:

HTTP status:
  204 (No Content)

Delete a Goal

Method DELETE
URI path api/1.0/goal/by_goal_id
Matrix params id [1]
Query params -
   
Returns -

Example:

Request header:

DELETE /api/1.0/goal/by_goal_id;id=8e81973f-51f3-4769-9627-885546d7c450 HTTP/1.1
Host: api.videoplaza.com
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  204 (No Content)
Method DELETE
URI path api/1.0.cpvext/goal/by_goal_id
Matrix params id [1]
Query params -
   
Returns -

Example:

Request header:

DELETE /api/1.0.cpvext/goal/by_goal_id;id=eece5f87-f34e-41f0-921e-dbd44bbf3280 HTTP/1.1
Host: api.videoplaza.com
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  204 (No Content)

List Goal(s) by Id

Method GET
URI path api/1.0/goal/by_goal_id
Matrix params id [1...n]
Query params -
   
Returns list of goals

Example:

Request header:

GET /api/1.0/goal/by_goal_id;id=2b0d9c09-4256-448c-af54-a9d36596e5fb HTTP/1.1
Host: api.videoplaza.com
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>
    <goalBean>
        <budget>
            <value>0.0</value>
        </budget>
        <campaignId>c3abb649-e45f-4692-a467-083e9968af6b</campaignId>
        <cpm>
            <value>0.0</value>
        </cpm>
        <end>2016-10-30T00:00:00+0200</end>
        <formatType>POSTROLL</formatType>
        <goalValue>0.0</goalValue>
        <id>2b0d9c09-4256-448c-af54-a9d36596e5fb</id>
        <name>Royco Postroll</name>
        <start>2016-09-30T00:00:00+0200</start>
        <type>IMPRESSION</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>
</collection>
Method GET
URI path api/1.0.cpvext/goal/by_goal_id
Matrix params id [1...n]
Query params -
   
Returns list of goals

Example:

Request header:

GET /api/1.0.cpvext/goal/by_goal_id;id=76c28cc8-6e20-42a1-af84-dc25655e9dc9 HTTP/1.1
Host: api.videoplaza.com
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>
    <goalBean>
        <campaignId>135ae70d-0e70-4d52-a71b-f9d95745fc74</campaignId>
        <cpm>
            <value>0.0</value>
        </cpm>
        <end>2017-05-05T00:00:00+02:00</end>
        <formatType>PREROLL</formatType>
        <goalValue>25000.0</goalValue>
        <id>76c28cc8-6e20-42a1-af84-dc25655e9dc9</id>
        <name>Royco 25% Ad Completion goal</name>
        <pricingModel>CPMV_25</pricingModel>
        <pricingValue>
            <value>20.0</value>
        </pricingValue>
        <start>2017-04-25T00:00:00+02:00</start>
        <type>FIRST_QUARTILE</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>
</collection>

List Goal(s) by Campaign Id

Method GET
URI path api/1.0/goal/by_campaign_id
Matrix params id [1...n]
Query params -
   
Returns list of goals

Example:

Request header:

GET /api/1.0/goal/by_campaign_id;id=c3abb649-e45f-4692-a467-083e9968af6b HTTP/1.1
Host: api.videoplaza.com
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>
    <goalBean>
        <budget>
            <value>0.0</value>
        </budget>
        <campaignId>c3abb649-e45f-4692-a467-083e9968af6b</campaignId>
        <cpm>
            <value>0.0</value>
        </cpm>
        <end>2016-10-30T00:00:00+0200</end>
        <formatType>POSTROLL</formatType>
        <goalValue>0.0</goalValue>
        <id>2b0d9c09-4256-448c-af54-a9d36596e5fb</id>
        <name>Royco Postroll</name>
        <start>2016-09-30T00:00:00+0200</start>
        <type>IMPRESSION</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>
    <goalBean>
        <budget>
            <value>0.0</value>
        </budget>
        <campaignId>c3abb649-e45f-4692-a467-083e9968af6b</campaignId>
        <cpm>
            <value>0.0</value>
        </cpm>
        <end>2016-10-30T00:00:00+0200</end>
        <formatType>PREROLL</formatType>
        <goalValue>30000.0</goalValue>
        <id>36597e76-1582-4983-8e44-8c3fec0f2a26</id>
        <name>Royco Sauce</name>
        <start>2016-09-30T00:00:00+0200</start>
        <type>IMPRESSION</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>
    <goalBean>
        <budget>
            <value>0.0</value>
        </budget>
        <campaignId>c3abb649-e45f-4692-a467-083e9968af6b</campaignId>
        <cpm>
            <value>0.0</value>
        </cpm>
        <end>2016-10-30T00:00:00+0200</end>
        <formatType>PREROLL</formatType>
        <goalValue>30000.0</goalValue>
        <id>d1e8ba62-72a3-41f4-8875-38d592b38570</id>
        <name>Royco Soup</name>
        <start>2016-09-30T00:00:00+0200</start>
        <type>IMPRESSION</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>
</collection>
Method GET
URI path api/1.0.cpvext/goal/by_campaign_id
Matrix params id [1...n]
Query params -
   
Returns list of goals

Example:

Request header:

GET /api/1.0.cpvext/goal/by_campaign_id;id=135ae70d-0e70-4d52-a71b-f9d95745fc74 HTTP/1.1
Host: api.videoplaza.com
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>
    <goalBean>
        <campaignId>135ae70d-0e70-4d52-a71b-f9d95745fc74</campaignId>
        <cpm>
            <value>0.0</value>
        </cpm>
        <end>2017-05-24T00:00:00+02:00</end>
        <formatType>PREROLL</formatType>
        <goalValue>20000.0</goalValue>
        <id>524a9a9b-69c9-49bf-aa98-cbda517f5d60</id>
        <name>Royco Impression goal</name>
        <pricingModel>NO_PRICING</pricingModel>
        <pricingValue>
            <value>0.0</value>
        </pricingValue>
        <start>2017-04-24T10:12:40+02:00</start>
        <type>IMPRESSION</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>
    <goalBean>
        <campaignId>135ae70d-0e70-4d52-a71b-f9d95745fc74</campaignId>
        <cpm>
            <value>0.0</value>
        </cpm>
        <end>2017-05-05T00:00:00+02:00</end>
        <formatType>PREROLL</formatType>
        <goalValue>25000.0</goalValue>
        <id>76c28cc8-6e20-42a1-af84-dc25655e9dc9</id>
        <name>Royco 25% Ad Completion goal</name>
        <pricingModel>CPMV_25</pricingModel>
        <pricingValue>
            <value>20.0</value>
        </pricingValue>
        <start>2017-04-25T00:00:00+02:00</start>
        <type>FIRST_QUARTILE</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>
    <goalBean>
        <campaignId>135ae70d-0e70-4d52-a71b-f9d95745fc74</campaignId>
        <cpm>
            <value>0.0</value>
        </cpm>
        <end>2017-05-11T00:00:00+02:00</end>
        <formatType>PREROLL</formatType>
        <goalValue>10000.0</goalValue>
        <id>bb9da0a2-dce7-4f61-b9f9-d728d21203df</id>
        <name>Royco 100% Ad Completion goal</name>
        <pricingModel>CPMV_100</pricingModel>
        <pricingValue>
            <value>10.0</value>
        </pricingValue>
        <start>2017-04-26T00:00:00+02:00</start>
        <type>COMPLETE</type>
        <unlimitedImpressions>false</unlimitedImpressions>
        <variant>NORMAL</variant>
    </goalBean>
</collection>

Was this article helpful?