Goal Requests

Getting Started

  • Base URL, depending on which goal types you use:
    • https://api.videoplaza.com/api/1.0/goal: you are using only share of voice, impression, and unlimited impression goals.
    • https://api.videoplaza.com/api/1.0.cpvext/goal: you are using all existing goal types.
  • 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 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: 0.01-1.0
  • IMPRESSION: 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 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. Setting the goalValue parameter for unlimited impression goals is ignored. Valid values for goal types:
    • SHARE_OF_VOICE: 0.01-1.0
    • IMPRESSION|FIRST_QUARTILE|SECOND_QUARTILE|THIRD_QUARTILE|COMPLETE|CLICK_THROUGH: any positive number
  2. 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
  3. 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
URL https://api.videoplaza.com/api/1.0/goal
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: 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
URL https://api.videoplaza.com/api/1.0.cpvext/goal
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: 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>
        <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
URL https://api.videoplaza.com/api/1.0/goal/by_goal_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: goal ID
Query params -
Body Request Body Format
Success response

HTTP status: 204 No Content

Header: -

Body: -

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
URL https://api.videoplaza.com/api/1.0.cpvext/goal/by_goal_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: goal ID
Query params -
Body Request Body Format
Success response

HTTP status: 204 No Content

Header: -

Body: -

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
URL https://api.videoplaza.com/api/1.0/goal/by_goal_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: goal ID
Query params -
Body -
Success response

HTTP status: 204 No Content

Header: -

Body: -

Example:

Request header:

DELETE /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: NA

Success response:

HTTP status:
  204 (No Content)
Method DELETE
URL https://api.videoplaza.com/api/1.0.cpvext/goal/by_goal_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: goal ID
Query params -
Body -
Success response

HTTP status: 204 No Content

Header: -

Body: -

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
Content-­type: application/xml
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  204 (No Content)

List Goal(s) by ID

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

HTTP status: 200 OK

Header: -

Body: 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
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>
    <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
URL https://api.videoplaza.com/api/1.0.cpvext/goal/by_goal_id
Header Authentication header (x-o-api-key)
Content type application/xml
Matrix params id: goal ID
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: 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
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>
    <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
URL https://api.videoplaza.com/api/1.0/goal/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 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
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>
    <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
URL https://api.videoplaza.com/api/1.0.cpvext/goal/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 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
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>
    <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?