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
{
"$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:
|
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:
|
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
{
"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>
{
"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" : "Company2 - 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" : [ ]
}
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.
{
"status": "active",
"periodDays": 30,
"endDate": "2016-08-01T00:00:00-00:00",
"tags": [
{
"id": 1575
}
],
"labels": [
"label1",
"label2"
],
"frequency": 5,
"insideIframe": true,
"targetPhints": [
{
"operator": "eq",
"key": "make",
"value": "Chevy"
}
],
"name": "test-123456789",
"maxLoadTime": 5000,
"targetUser": {
"id": 24
},
"sites": [
{
"id": 2206
}
],
"priority": 1,
"maxAvgTagExecTime": 500,
"startDate": "2016-06-12T00:00:00-00:00"
}
{
"status": "active",
"startDate": "2016-06-12T00:00:00+00:00",
"endDate": "2016-07-01T00:00:00+00:00",
"targetPhints": [
{
"operator": "eq",
"value": "Chevy",
"id": 883,
"key": "make"
}
],
"maxLoadTime": 5000,
"tags": [
{
"id": 1575,
"name": "Sample tag"
}
],
"periodDays": 30,
"labels": [
"label1",
"label2"
],
"sites": [
{
"id": 2206,
"name": "Buyer site"
}
],
"priority": 1,
"frequency": 5,
"updatedAt": "2016-05-29T00:42:57+00:00",
"insideIframe": true,
"partner": {
"id": 486,
"name": "Buyer"
},
"maxAvgTagExecTime": 500,
"id": 3840,
"createdAt": "2016-05-29T00:42:57+00:00",
"name": "test-123456789"
}
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.
{
"status": "active",
"startDate": "2016-06-12T00:00:00+00:00",
"endDate": "2016-07-01T00:00:00+00:00",
"targetPhints": [
{
"operator": "eq",
"value": "Chevy",
"id": 883,
"key": "Make"
}
],
"maxLoadTime": 5000,
"tags": [
{
"id": 1575,
"name": "Sample tag"
}
],
"targetUser": {
"id": 24,
"name": "Target ABCD"
},
"periodDays": 30,
"labels": [
"label3"
],
"targetSite": {
"id": 96
},
"sites": [
{
"id": 2206,
"name": "Buyer site"
}
],
"priority": 1,
"frequency": 5,
"updatedAt": "2016-06-29T00:42:57+00:00",
"insideIframe": true,
"partner": {
"id": 486,
"name": "Buyer"
},
"maxAvgTagExecTime": 500,
"id": 3840,
"createdAt": "2016-06-29T00:42:57+00:00",
"name": "test-123456789"
}
{
"status": "active",
"startDate": "2016-06-12T00:00:00+00:00",
"endDate": "2016-07-01T00:00:00+00:00",
"targetPhints": [
{
"operator": "eq",
"value": "Chevy",
"id": 883,
"key": "Make"
}
],
"maxLoadTime": 5000,
"tags": [
{
"id": 1575,
"name": "Sample tag"
}
],
"targetUser": {
"id": 24,
"name": "Target ABCD"
},
"periodDays": 30,
"labels": [
"label3"
],
"sites": [
{
"id": 2206,
"name": "Buyer site"
}
],
"priority": 1,
"frequency": 5,
"updatedAt": "2016-06-29T00:42:59+00:00",
"insideIframe": true,
"partner": {
"id": 486,
"name": "Buyer"
},
"maxAvgTagExecTime": 500,
"id": 3840,
"createdAt": "2016-06-29T00:42:57+00:00",
"name": "test-123456789"
}
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.
[
{
"status": "active",
"startDate": "2016-06-17T00:00:00+00:00",
"endDate": "2016-07-01T00:00:00+00:00",
"targetPhints": [
{
"operator": "eq",
"key": "make",
"id": 552,
"value": "Chevy"
}
],
"maxLoadTime": 5000,
"tags": [
{
"id": 1575,
"name": "Sample tag"
}
],
"periodDays": 30,
"labels": [
"label1",
"label2"
],
"sites": [
{
"id": 2206,
"name": "Buyer site"
}
],
"priority": 1,
"frequency": 5,
"updatedAt": "2016-06-15T06:20:50+00:00",
"insideIframe": true,
"partner": {
"id": 486,
"name": "Buyer"
},
"isAlwaysOn": true,
"maxAvgTagExecTime": 500,
"id": 2568,
"createdAt": "2016-06-15T06:20:50+00:00",
"name": "test-123456789-updated"
},
{
"status": "active",
"startDate": "2016-06-17T00:00:00+00:00",
"endDate": "2016-07-01T00:00:00+00:00",
"targetPhints": [
{
"operator": "eq",
"key": "Make",
"id": 552,
"value": "Chevy"
}
],
"maxLoadTime": 5000,
"tags": [
{
"id": 1575,
"name": "Sample tag"
}
],
"periodDays": 30,
"labels": [
"label1",
"label2"
],
"sites": [
{
"id": 2206,
"name": "Buyer site"
}
],
"priority": 1,
"frequency": 5,
"updatedAt": "2016-06-15T06:22:00+00:00",
"insideIframe": true,
"partner": {
"id": 486,
"name": "Buyer"
},
"isAlwaysOn": true,
"maxAvgTagExecTime": 500,
"id": 12345,
"createdAt": "2016-06-15T06:20:50+00:00",
"name": "test-987654321-updated"
}
]
{
"items": [
{
"item": {
"status": "active",
"startDate": "2016-06-15T00:00:00+00:00",
"endDate": "2016-07-01T00:00:00+00:00",
"targetPhints": [
{
"operator": "eq",
"value": "Chevy",
"id": 552,
"key": "Make"
}
],
"maxLoadTime": 5000,
"tags": [
{
"id": 1575,
"name": "Sample tag"
}
],
"targetUser": {
"id": 24,
"name": "Target ABCD"
},
"periodDays": 30,
"labels": [
"label1",
"label2"
],
"sites": [
{
"id": 2206,
"name": "Buyer site"
}
],
"priority": 1,
"frequency": 5,
"updatedAt": "2016-06-15T06:23:24+00:00",
"insideIframe": true,
"partner": {
"id": 486,
"name": "Buyer"
},
"isAlwaysOn": true,
"maxAvgTagExecTime": 500,
"id": 2568,
"createdAt": "2016-06-15T06:20:50+00:00",
"name": "test-123456789"
},
"httpStatusCode": 200
},
{
"item": {
"status": 404,
"o:errorCode": "BK-38001",
"title": "Schedule was not found",
"detail": "Schedule with ID '12345' was not found",
"instance": "https://services.bluekai.com/rest/schedules",
"type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5"
},
"httpStatusCode": 404
}
],
"size": 2
}
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. |