Goal Rules Requests

Audience targeting, browser/OS targeting, IP targeting, as well as capping the maximum number of impressions per 15 minutes, 30 minutes, and goal lifetime 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.

There is a version 2 of the Goal Rules REST API endpoint. This endpoint complements the Goal API but it uses a different base URL and communication format. Audience targeting, browser/OS targeting, IP targeting, as well as capping the maximum number of impressions per 15 minutes, 30 minutes, and goal lifetime is only supported in version 2. For more information, see Goal Rules v2 Requests.

Getting Started

  • Base URL: https://api.videoplaza.com/api/1.0/goal/rule.
  • Requests: GET and PUT 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: Targeting Rules
The Goal Rules endpoint allows you to:

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>

Update Goal Rules

Audience targeting, browser/OS targeting, IP targeting, as well as capping the maximum number of impressions per 15 minutes, 30 minutes, and goal lifetime 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.

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

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.

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 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>6ceb63e1-cddf-4083-949f-3d4c5d46462a</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)