Goal and goal rules 1.0 requests

Note:

The recommended combination of goal and goal rules endpoints, which provides the most complete support for all goal settings and goal targeting rules, is: Goal 1.0.cpvext endpoints for manipulating your goals and Goal rules v2 endpoints for manipulating goal targeting rules.

  • Goal 1.0.cpvext endpoints have support for all goal types, pricing models, impression and event caps, and mid-roll break targeting, which is not supported through Goal 1.0 endpoints described below. You should migrate to Goal 1.0.cpvext endpoints if you are still using Goal 1.0 endpoints for manipulating your goals.
  • Goal rules v2 endpoints support getting and updating all targeting rules for all goal types. You should migrate to Goal rules v2 endpoints if you are still using one of the below:
    • Goal rules 1.0 endpoints described below, which only support getting and updating targeting rules for share of voice, impression, priority unreserved (RTB), and unlimited impression goals, and have no support for audience targeting, browser/OS targeting, and IP targeting
    • Goal rules 1.0.cpvext endpoints, which do not have support for audience targeting, browser/OS targeting, and IP targeting.

Getting started

  • Base URL: https://api.videoplaza.com/api/1.0/goal
  • 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:
The goal rules endpoints allow you to:

Goal: Request body format

To create or update a share of voice, impression, priority unreserved (RTB), 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>    <!-- End date and time must be after start date and time -->
    <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>    <!-- Use up to 255 characters -->
    <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; start date and time cannot be in the past and if you pass in a past date and time, it gets set to the date and time of creation -->
    <type>SHARE_OF_VOICE|IMPRESSION|UNLIMITED_IMPRESSION|RTB</type>    <!-- Required -->
    <unlimitedImpressions>boolean</unlimitedImpressions>
    <variant>NORMAL|BUMPER</variant>    <!-- Required, "BUMPER" corresponds to sponsor goal mode in the Pulse UI --> 
</goalBean>
Note:
  • Passing in a start date and time in the past is only allowed if the end date and time is also in the past, as this means that the goal is not active and delivery is not affected. In this case, at creation, the start parameter does not get set to the date and time of goal creation.
  • The start date and time of active goals can only be updated to a future start date and time, starting from the current date and time, or remain set to the original creation date and time in the past.
  • The start date and time of upcoming goals can only be updated to a future start date and time, starting from the current date and time.
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

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 Goal: 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

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 Goal: 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>
        <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)

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)

Get goal by goal 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: goal bean

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>

List goals 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>

Goal rules: Request body format

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

<rulesBean>
    <parentId>string</parentId>    <!-- Goal ID -->
    <content>
        <resourceId>string</resourceId>    <!-- Category ID -->
        <!-- <resourceName>string</resourceName> (Category name; setting this value is ignored) -->
        <ruleType>ALL_OF|AT_LEAST_ONE_OF|NONE_OF</ruleType> 
        <variableType>SITE</variableType>
    </content>
    <frequencyCappings>
        <impressions>integer</impressions>    <!-- Number of impressions to allow in this time period -->
        <timeUnit>FIVE_MINUTES|TEN_MINUTES|QUARTER_HOUR|HALF_HOUR|HOUR|DAY|WEEK|MONTH|GOAL_LIFETIME</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 set based on the account'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>    <!-- Content Partner ID/Tag value -->
        <!-- <resourceName>string</resourceName> (Content Partner/Tag name; setting this value is ignored) -->
        <ruleType>ALL_OF|AT_LEAST_ONE_OF|NONE_OF</ruleType>
        <variableType>CONTENT_PARTNER|TAG</variableType>
    </tags>
    <accountCustomParameters>
        <ignoreParent>boolean</ignoreParent>
        <parameterName>acp.paramName</parameterName>  <!-- paramName needs to match the ad request parameter name defined for your Pulse account -->
        <rules>
            <ruleType>AT_LEAST_ONE_OF|NONE_OF</ruleType>
            <value>string</value>  <!-- Value for the corresponding acp parameter defined for your Pulse account, see below for more information -->
        </rules>
    </accountCustomParameters>
    <ignoreParentContentRules>boolean</ignoreParentContentRules>
    <ignoreParentFrequencyRules>boolean</ignoreParentFrequencyRules>
    <ignoreParentLocationRules>boolean</ignoreParentLocationRules>
    <ignoreParentTagRules>boolean</ignoreParentTagRules>
    <ignoreParentTimeRules>boolean</ignoreParentTimeRules>
</rulesBean>

If you set a specific time restriction combination to active, then the rest is considered inactive. You can have both active and inactive rules if you want to set a portion of the active period to be inactive. For example, active on Saturday between 08:00 a.m. and 11:00 a.m., but inactive for 15 minutes on Saturday, between 10:00 a.m. and 10:15 a.m

Time restriction set to, for example, <toHour>5</toHour> and <toMinute>59</toMinute> actually means it is set to 05:58:59 (hour 5, minute 58, second 59). To capture the last minute of the hour in this example, you need to set the time restriction as <toHour>6</toHour> and <toMinute>0</toMinute>.

To extend a rule to the next day, use <toHour>0</toHour> and <toMinute>0</toMinute>.

You can add a maximum of 20 values for one account custom paramater. The account custom parameter values cannot contain any spaces or any of the following characters: comma (,), semicolon (;), double quote/quotation mark ("), single quote/apostrophe ('), backslash (\), pipe (|), tilde (~), or ampersand (&).

The ignoreParentRules parameters can be set to:
  • true: If you want to partially or completely change the targeting for a goal, you need to ignore the corresponding parent (campaign) rule that does not match the new targeting. A configured (not empty) parent rule has to be ignored when it partially or entirely conflicts with the desired targeting outcome.
  • false:
    • When the parent (campaign) rule is empty (not configured). If a campaign targeting rule is empty, Pulse treats it as a matching rule, because an empty rule matches all requests.
    • When the child (goal) rule is exactly the same as the parent (campaign) rule or is a subset of the parent (campaign) rule.

    For more information, see Apply and ignore targeting rules.

Update goal rules

Audience targeting, browser/OS targeting, and IP targeting is not supported through this API. A possible workaround is to add these targeting rules through targeting templates and then import or link the targeting template to a goal. For more information, see Targeting Template API.

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

HTTP status: 204 No Content

Header: -

Body: -

Example

Request header

PUT /api/1.0/goal/rule/by_goal_id;id=f728064b-803f-4a82-a5d7-9efab5d4538a 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>
    <accountCustomParameters>
        <ignoreParent>true</ignoreParent>
        <parameterName>acp.genre</parameterName>
        <rules>
            <ruleType>AT_LEAST_ONE_OF</ruleType>
            <value>Comedy</value>
        </rules>
    </accountCustomParameters>
    <accountCustomParameters>
        <ignoreParent>true</ignoreParent>
        <parameterName>acp.network</parameterName>
        <rules>
            <ruleType>AT_LEAST_ONE_OF</ruleType>
            <value>Network1</value>
        </rules>
    </accountCustomParameters>
    <content>
        <resourceId>dc74b090-c275-4646-a37f-4d5cff09997a</resourceId>
        <resourceName>Entertainment</resourceName>
        <ruleType>ALL_OF</ruleType>
        <variableType>SITE</variableType>
    </content>
    <content>
        <resourceId>df5480fd-ca38-43c8-a44c-4240965e2023</resourceId>
        <resourceName>Sport</resourceName>
        <ruleType>NONE_OF</ruleType>
        <variableType>SITE</variableType>
    </content>
    <frequencyCappings>
        <impressions>3</impressions>
        <timeUnit>HOUR</timeUnit>
    </frequencyCappings>
    <frequencyCappings>
        <impressions>15</impressions>
        <timeUnit>DAY</timeUnit>
    </frequencyCappings>
    <ignoreParentContentRules>true</ignoreParentContentRules>
    <ignoreParentFrequencyRules>true</ignoreParentFrequencyRules>
    <ignoreParentLocationRules>true</ignoreParentLocationRules>
    <ignoreParentTagRules>true</ignoreParentTagRules>
    <ignoreParentTimeRules>true</ignoreParentTimeRules>
    <locations>
        <allowed>true</allowed>
        <country>sweden</country>
        <id>752</id>
        <iso2>se</iso2>
        <locationType>COUNTRY</locationType>
    </locations>
    <locations>
        <allowed>true</allowed>
        <country>sweden</country>
        <id>71</id>
        <locationType>REGION</locationType>
        <region>sweden (?)</region>
    </locations>
    <locations>
        <allowed>false</allowed>
        <country>norway</country>
        <id>578</id>
        <iso2>no</iso2>
        <locationType>COUNTRY</locationType>
    </locations>
    <parentId>f728064b-803f-4a82-a5d7-9efab5d4538a</parentId>
    <tags>
        <resourceId>entertainment</resourceId>
        <resourceName>entertainment</resourceName>
        <ruleType>ALL_OF</ruleType>
        <variableType>TAG</variableType>
    </tags>
    <tags>
        <resourceId>idol</resourceId>
        <resourceName>idol</resourceName>
        <ruleType>AT_LEAST_ONE_OF</ruleType>
        <variableType>TAG</variableType>
    </tags>
    <tags>
        <resourceId>reality_show</resourceId>
        <resourceName>reality_show</resourceName>
        <ruleType>AT_LEAST_ONE_OF</ruleType>
        <variableType>TAG</variableType>
    </tags>
    <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>

Success response

HTTP status:
  204 (No Content)

List goal rules by goal ID

Method GET
URL https://api.videoplaza.com/api/1.0/goal/rule/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: rulesBean

Example

Request header

GET /api/1.0/goal/rule/by_goal_id;id=f728064b-803f-4a82-a5d7-9efab5d4538a 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>
    <accountCustomParameters>
        <ignoreParent>false</ignoreParent>
        <parameterName>acp.genre</parameterName>
    </accountCustomParameters>
    <accountCustomParameters>
        <ignoreParent>false</ignoreParent>
        <parameterName>acp.network</parameterName>
    </accountCustomParameters>
    <content>
        <resourceId>0d828b6b-5753-47a9-9a72-8639765193b3</resourceId>
        <resourceName>News</resourceName>
        <ruleType>AT_LEAST_ONE_OF</ruleType>
        <variableType>SITE</variableType>
    </content>
    <content>
        <resourceId>dc74b090-c275-4646-a37f-4d5cff09997a</resourceId>
        <resourceName>Entertainment</resourceName>
        <ruleType>AT_LEAST_ONE_OF</ruleType>
        <variableType>SITE</variableType>
    </content>
    <frequencyCappings>
        <impressions>2</impressions>
        <timeUnit>HOUR</timeUnit>
    </frequencyCappings>
    <ignoreParentContentRules>false</ignoreParentContentRules>
    <ignoreParentFrequencyRules>false</ignoreParentFrequencyRules>
    <ignoreParentLocationRules>false</ignoreParentLocationRules>
    <ignoreParentTagRules>false</ignoreParentTagRules>
    <ignoreParentTimeRules>false</ignoreParentTimeRules>
    <parentId>f728064b-803f-4a82-a5d7-9efab5d4538a</parentId>
</rulesBean>