Schedules API

You can implement the schedules REST API to provide instructions for firing tags. Schedules specify where, when, and for whom third-party tags are fired from a container. Creating a schedule entails selecting the tags, containers, and targets you previously created and then configuring the maximum load time, priority, and other quality of service controls for the tag.

Note: Users no longer create campaigns in the Oracle Data Cloud platform UI. The campaign workflow is now part of the audience workflow. The platform still uses campaigns to manage audience data delivery however. They are created automatically when a UI user delivers an audience. In the APIs, you create and use campaigns as before.

In this topic

Explore the API

The embedded I/O doc below enables you to explore the API. The I/O doc explains the parameters for each method and provides templates for your calls. You cannot make live API calls from the tool, however.

Open the link below in a new tab to see the I/O doc in a three-pane format.

https://schedules7.docs.apiary.io

For help with this API, contact My Oracle Support (MOS).

Service URI

The URI for the schedules API is:

services.bluekai.com/rest/schedules

Schema

The URI for the schedules API schema is:

services.bluekai.com/rest/schedules.schema

Expand to see the schedules schema:

{
  "$schema" : "https://json-schema.org/draft-04/schema#",
  "id" : "#schedule",
  "type" : "object",
  "title" : "Schedule schema",
  "description" : "This schema describes inner structure of a schedule resource"                    ,
  "additionalProperties" : false,
  "properties" : {
    "id" : {
      "type" : "integer",
      "description" : "Reference ID within a resource collection",
      "minimum" : 1,
      "o:sortable" : true,
      "o:queryable" : true
    },
    "name" : {
      "type" : "string",
      "description" : "Name of the Resource",
      "minLength" : 1,
      "o:sortable" : true
    },
    "partner" : {
      "type" : "object",
      "description" : "This schema describes inner structure of a stub resource with id and name",
      "additionalProperties" : false,
      "properties" : {
        "id" : {
          "type" : "integer",
          "description" : "ID of the associated partner"
        },
        "name" : {
          "type" : "string",
          "description" : "Name of the Resource",
          "minLength" : 1
        }
      },
      "required" : [ "id" ]
    },
    "status" : {
      "enum" : [ "active", "deleted", "disabled", "creating", "updating" ],
      "description" : "Describes status of current resource",
      "default" : "active",
      "o:queryable" : true,
      "o:sortable" : true
    },
    "targetUser" : {
      "$ref" : "#stub"
    },
    "targetSite" : {
      "$ref" : "#stub"
    },
    "targetPhints" : {
      "type" : "array",
      "items" : {
        "type" : "object",
        "description" : "This schema describes inner structure of a phint resource of a schedule target",
        "additionalProperties" : false,
        "properties" : {
          "id" : {
            "type" : "integer",
            "description" : "Reference ID of the resource"
          },
          "key" : {
            "type" : "string",
            "description" : "phint key for targeting"
          },
          "operator" : {
            "type" : "string",
            "description" : "phint operator for targeting"
          },
          "value" : {
            "type" : "string",
            "description" : "phint value for targeting"
          }
        },
        "required" : [ "key", "operator", "value" ]
      }
    },
    "tags" : {
      "type" : "array",
      "items" : {
        "$ref" : "#stub"
      },
      "minItems" : 1
    },
    "sites" : {
      "type" : "array",
      "items" : {
        "$ref" : "#stub"
      }
    },
    "priority" : {
      "type" : "integer",
      "default" : 100,
      "description" : "Priority of the schedule resource",
      "o:sortable" : true
    },
    "createdAt" : {
      "type" : "string",
      "format" : "date-time",
      "description" : "Schedule created date and time in the format yyyy-MM-ddTHH:mm:ssZ",
      "minLength" : 20,
      "maxLength" : 29,
      "o:sortable" : true,
      "o:queryable" : true
    },
    "updatedAt" : {
      "type" : "string",
      "format" : "date-time",
      "description" : "Schedule updated date and time in the format yyyy-MM-ddTHH:mm:ssZ",
      "minLength" : 20,
      "maxLength" : 29,
      "o:sortable" : true,
      "o:queryable" : true
    },
    "startDate" : {
      "type" : "string",
      "format" : "date-time",
      "description" : "Schedule start date in the format yyyy-MM-ddTHH:mm:ssZ",
      "minLength" : 20,
      "maxLength" : 29,
      "o:sortable" : true,
      "o:queryable" : true
    },
    "endDate" : {
      "type" : "string",
      "format" : "date-time",
      "description" : "Schedule end date in the format yyyy-MM-ddTHH:mm:ssZ",
      "minLength" : 20,
      "maxLength" : 29,
      "o:sortable" : true,
      "o:queryable" : true
    },
    "maxLoadTime" : {
      "type" : "integer",
      "description" : "Max load time of schedule in milliseconds"
    },
    "periodDays" : {
      "type" : "integer",
      "description" : "Number of days while specifying frequency"
    },
    "frequency" : {
      "type" : "integer",
      "description" : "Frequency of the schedule per periodDays"
    },
    "insideIframe" : {
      "type" : "boolean",
      "default" : true,
      "description" : "Flag denoting if inside iframe or not"
    },
    "isAlwaysOn" : {
      "type" : "boolean",
      "default" : true,
      "description" : "Flag denoting if it's always on or not"
    },
    "maxAvgTagExecTime" : {
      "type" : "integer",
      "default" : 5000,
      "description" : "Maximum average tag execution time in milliseconds"
    },
    "labels" : {
      "type" : "array",
      "uniqueItems" : true,
      "items" : {
        "type" : "string"
      }
    },
    "adminState" : {
      "type" : "string"
    },
    "note" : {
      "type" : "string"
    },
    "hidden" : {
      "type" : "boolean",
      "default" : false,
      "o:queryable" : true,
      "description" : "Flag denoting if schedule is system generated or not"
    }
  },
  "required" : [ "name", "startDate", "tags" ],
  "links" : [ {
    "rel" : "search",
    "href" : "#",
    "schema" : {
      "type" : "object",
      "properties" : {
        "q" : {
          "type" : "string",
          "format" : "scim"
        },
        "since" : {
          "type" : "string",
          "format" : "date-time",
          "description" : "Query parameter to return resources created after this date in the format yyyy-MM-ddTHH:mm:ssZ"
        },
        "until" : {
          "type" : "string",
          "format" : "date-time",
          "description" : "Query parameter to return resources created before this date in the format yyyy-MM-ddTHH:mm:ssZ"
        },
        "nameOrId" : {
          "type" : "string",
          "description" : "Filter by Name or ID of the resource"
        },
        "label" : {
          "type" : "string",
          "description" : "Filter by label of the resource"
        }
      }
    }
  } ]
}

Properties

The schedules responses include the following information with each schedule returned.

Property	Type	Description
`createdAt`	date	A timestamp in ISO 8601 date and time format (yyyy-MM-dd'T'HH:mm:ssZ) indicating when the campaign was created. For example: `2016-06-18T17:46:32-05:00` You can query for and sort by this parameter.
`endDate`	date	A timestamp in ISO 8601 date and time format (yyyy-MM-dd'T'HH:mm:ssZ) indicating when the schedule will stop running. For example: `2016-08-18T17:00:00-05:00` You can query for and sort by this parameter.
`frequency`	integer	Frequency of the schedule per `periodDays` for which the tag is eligible to be fired per user. For example, if you specify a `frequency` of 1 and a `periodDays` of 30, your third-party tags will be fired once per user within a 30 day period.
`id`	integer	The unique ID of the tag schedule. You can sort by and query by this parameter.
`insideIframe`	boolean	Indicates whether the tag is scheduled to fire in an iframe for enhanced security (the default is true) or not (false). A value of false indicates that the tag can be placed directly on the first-party page, which requires a special container tag.
`isAlwaysOn`	boolean	Indicates whether the schedule is always on (true). If `isAlwaysOn` is set to true (the default), `frequency` and `periodDays` will be ignored and tags in the schedule are fired as long as the targeting conditions are met.
`labels`	array	A list of comma-delimited strings serving as labels for the schedule
`maxAvgTagExecTime`	integer	The maximum average tag execution time in milliseconds in which scheduled tags should render or the tag will shut down. The default value is 5000 (five seconds). If `maxAvgTagExecTime` differs from the tag latency settings, the more restrictive setting applies. For example, if the tag latency settings uses a global max tag execution time of 1000 and `maxAvgTagExecTime` is set to 900, 900 is used.
`maxLoadTime`	integer	The maximum load time in milliseconds in which a scheduled tag must render or the tag will shut down. If the `maxLoadTime` value differs the tag latency settings, the more restrictive setting will apply. For example, if the tag latency settings use a maximum load time of 5000 and `maxLoadTime` is set to 6000, 5000 is used.
`name`	string	The name of the tag schedule. You can sort by this required parameter.
`note`	string	Any notes entered for the schedule
`partner`	object	An object that describes the partner associated with the tag
`periodDays`	integer	The number of days used for the specified `frequency`. For example, if `frequency` is set to 1 and `periodDays` is set to 30, your third-party tags will be fired once per user within a 30 day period.
`priority`	integer	The relative priority of the tag schedule used to determine the sequence of firing if there are multiple containers to be fired. The lower the value, the higher the priority. The default value is 100. You can sort by this field.
`sites`	array	A list of names and IDs of the sites on which the tags will be fired
`startDate`	date	A timestamp in ISO 8601 date and time format (yyyy-MM-dd'T'HH:mm:ssZ) indicating when the schedule was activated. For example: `2016-06-18T17:00:00-05:00` You can query for and sort by this required parameter.
`status`	string	Indicates whether the schedule is: `active` (the default): The tags can fire based on the schedule. `creating`: The schedule is in the process of being created. `disabled`: The schedule is on hold and its tags will not fire until the schedule is enabled. `updating`: The schedule is in the process of being updated. You can query for and sort by this parameter.
`tags`	array	A list of the names and IDs for the tags that will be fired by the schedule
`targetPhints`	array	An array of phint objects to be used for conditionally firing the tag. If specified, each object includes: `key` `value` `operator`: A conditional operator. The default value is `eq` (equals) `id` (optional): The unique ID of the phint For more details about phint targeting, see creating and managing targets.
`targetSite`	object	An object describing the site target associated with the schedule For more details about site targets, see creating and managing targets.
`targetUser`	object	An object describing the user target associated with the schedule For more details about user targets, see creating and managing targets.
`updatedAt`	date	A timestamp in ISO 8601 date and time format (yyyy-MM-dd'T'HH:mm:ssZ) indicating when the schedule was updated. For example: `2016-06-18T17:46:32-05:00` You can query for and sort by this parameter.

List schedules

To list multiple schedules, call GET https://services.bluekai.com/rest/schedules

Sample GET request: https://services.bluekai.com/rest/schedules?size=5&offset=0

Expand to see the sample response

{
  "items" : [ {
    "id" : 1,
    "name" : "Company1 US",
    "partner" : {
      "id" : 12,
      "name" : "Company1"
    },
    "status" : "active",
    "targetPhints" : [ ],
    "tags" : [ {
      "id" : 3009,
      "name" : "MediaTargeting Company Global Sync Pixel"
    }, {
      "id" : 3020,
      "name" : "Company1 - US - Retargeting"
    } ],
    "sites" : [ {
      "id" : 17001,
      "name" : "Company1 - US Priority"
    }, {
      "id" : 17002,
      "name" : "Company1 - US Priority_mobile"
    }, {
      "id" : 24212,
      "name" : "Company1 US - mWeb"
    }, {
      "id" : 50,
      "name" : "Company1 - US"
    } ],
    "priority" : 100,
    "createdAt" : "2016-01-28T14:47:52+00:00",
    "updatedAt" : "2016-06-11T20:44:04+00:00",
    "maxLoadTime" : 2000,
    "periodDays" : 30,
    "frequency" : 1,
    "insideIframe" : true,
    "maxAvgTagExecTime" : 1000,
    "labels" : [ ]
  }, {
    "id" : 2,
    "name" : "Company1 US Motors",
    "partner" : {
      "id" : 12,
      "name" : "Company1"
    },
    "status" : "disabled",
    "targetPhints" : [ ],
    "tags" : [ ],
    "sites" : [ {
      "id" : 2202,
      "name" : "Company1 test 1"
    }, {
      "id" : 20,
      "name" : "Company1 Motors"
    }, {
      "id" : 10371,
      "name" : "Company1 Motors_mobile"
    }, {
      "id" : 10402,
      "name" : "Company1 test 1_mobile"
    } ],
    "priority" : 1,
    "createdAt" : "2016-01-28T14:49:00+00:00",
    "updatedAt" : "2016-10-21T15:39:29+00:00",
    "maxLoadTime" : 1000,
    "periodDays" : 30,
    "frequency" : 1,
    "insideIframe" : true,
    "maxAvgTagExecTime" : 2000,
    "labels" : [ ]
  }, {
    "id" : 3,
    "name" : "Company1 CA",
    "partner" : {
      "id" : 12,
      "name" : "Company1"
    },
    "status" : "active",
    "targetPhints" : [ ],
    "tags" : [ {
      "id" : 2825,
      "name" : "Company2 - CA"
    }, {
      "id" : 5552,
      "name" : "Company2 - CA (eCommerce)"
    }, null, {
      "id" : 3009,
      "name" : "MediaTargeting Company Global Sync Pixel"
    }, {
      "id" : 4137,
      "name" : "CA - Company3 - All"
    }, {
      "id" : 4138,
      "name" : "CA - Company4 - All"
    } ],
    "sites" : [ {
      "id" : 725,
      "name" : "Company1 - CA"
    }, {
      "id" : 10386,
      "name" : "Company1 - CA_mobile"
    } ],
    "priority" : 1,
    "createdAt" : "2016-01-28T14:49:59+00:00",
    "updatedAt" : "2016-11-11T18:26:05+00:00",
    "maxLoadTime" : 1000,
    "periodDays" : 30,
    "frequency" : 1,
    "insideIframe" : true,
    "maxAvgTagExecTime" : 2000,
    "labels" : [ ]
  }, {
    "id" : 4,
    "name" : "Company1 CA Motors",
    "partner" : {
      "id" : 12,
      "name" : "Company1"
    },
    "status" : "disabled",
    "targetPhints" : [ ],
    "tags" : [ ],
    "sites" : [ {
      "id" : 922,
      "name" : "Company1 - CA Motors"
    }, {
      "id" : 10390,
      "name" : "Company1 - CA Motors_mobile"
    } ],
    "priority" : 1,
    "createdAt" : "2016-01-28T14:50:42+00:00",
    "updatedAt" : "2016-10-21T15:38:47+00:00",
    "maxLoadTime" : 1000,
    "periodDays" : 30,
    "frequency" : 1,
    "insideIframe" : true,
    "maxAvgTagExecTime" : 2000,
    "labels" : [ ]
  }, {
    "id" : 5,
    "name" : "Company1  UK",
    "partner" : {
      "id" : 12,
      "name" : "Company1"
    },
    "status" : "active",
    "targetPhints" : [ ],
    "tags" : [ null, null, {
      "id" : 3009,
      "name" : "MediaTargeting Company Global Sync Pixel"
    } ],
    "sites" : [ {
      "id" : 723,
      "name" : "Company1 - UK"
    }, {
      "id" : 10384,
      "name" : "Company1 - UK_mobile"
    } ],
    "priority" : 1,
    "createdAt" : "2016-01-28T14:51:14+00:00",
    "updatedAt" : "2016-02-25T07:48:46+00:00",
    "maxLoadTime" : 1000,
    "periodDays" : 30,
    "frequency" : 1,
    "insideIframe" : true,
    "maxAvgTagExecTime" : 1000,
    "labels" : [ ]
  } ],
  "totalResults" : 3373,
  "limit" : 5,
  "offset" : 0,
  "count" : 5,
  "hasMore" : true
}

GET a schedule

If you have the schedule's ID, you can request its information by calling GET https://services.bluekai.com/rest/schedules/<id>

Create a schedule

To create a tag schedule, call POST https://services.bluekai.com/rest/schedules and specify its required properties in the request body.

Update a schedule

To update a specific schedule, call PUT https://services.bluekai.com/rest/schedules/<id> and specify the updated properties in the request body.

Bulk update

To update multiple schedules, call PUT https://services.bluekai.com/rest/schedules and specify a request body that includes an array of schedule objects.

Response errors

For the most up-to-date list of error messages, call https://services.bluekai.com/rest/schedules.errors?bkuid=bkUserID&bksig=SignedString

If there is a problem with your campaigns request, the response will use one of the following error messages:

Code	Error message
BK-10001	Could not find resource for the specified path
BK-10002	Bad query parameters
BK-10003	Invalid JSON input
BK-10004	Input JSON does not pass schema validation
BK-10005	Input JSON contains bad property
BK-10006	Input JSON has missing properties
BK-10007	Input JSON has bad property that does not match min length requirement
BK-10008	Input JSON has bad property that does not match max length requirement
BK-10009	Not enough privileges to access requested resource
BK-10010	The request could not be completed by the service due to malformed data or syntax
BK-10011	Incorrect sorting parameter
BK-10012	Additional properties detected. Schema does not allow extra properties to be present
BK-10013	Incorrect expand parameter
BK-10014	Incorrect q query parameter syntax
BK-10015	Property has unacceptable/bad format
BK-10016	Property value does not appear on the list of acceptable values
BK-10017	Array must not contain duplicate entries
BK-38001	Schedule was not found
BK-38002	Schedule status is invalid
BK-38003	Tag was not found
BK-38004	Site was not found
BK-38005	Target was not found

Related API calls

Here are the API calls you will typically make before you use the schedules API:

Before schedules API	Use case
Containers API	Create and manage sites in the Oracle Data Cloud platform. A container manages the third-party tags on your desktop and mobile sites and collects user data that is pushed into your DMP.

Learn more

Date format

Scheduling tags