Campaigns REST API
You can implement the Oracle Data Cloud campaigns REST API to create and manage campaigns. A campaign provides instructions to the Oracle Data Cloud platform for delivering your audience to Oracle Data Cloud partners. For example, you can use the campaigns API to specify your campaign's schedule, maximum bid price, budget, and other configuration parameters. There is also a pixel URL parameter that tells the DMP where to deliver your campaign data.
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.
For help with this API, contact My Oracle Support (MOS).
Service URI
The URI for the campaigns API is:
services.bluekai.com/rest/campaigns
Schema
The URI for the campaigns API schema is:
services.bluekai.com/rest/campaign.schema
Expand to see the campaign schema:
{
"$schema" : "https://json-schema.org/draft-04/schema#",
"id" : "#campaign",
"type" : "object",
"title" : "Campaign schema",
"description" : "This schema describes inner structure of a campaign 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,
"maxLength" : 120,
"o:sortable" : true,
"o:queryable" : 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" : "Reference ID within a resource collection",
"minimum" : 1
},
"name" : {
"type" : "string",
"description" : "Name of the Resource",
"minLength" : 1
}
}
},
"audience" : {
"type" : "object",
"description" : "This schema describes inner structure of a stub resource with id and name",
"additionalProperties" : false,
"properties" : {
"id" : {
"type" : "integer",
"description" : "Reference ID within a resource collection",
"minimum" : 1
},
"name" : {
"type" : "string",
"description" : "Name of the Resource",
"minLength" : 1
}
},
"required" : [ "id" ]
},
"bid" : {
"type" : "number",
"description" : "Bid value"
},
"pacingGoal" : {
"type" : "number",
"description" : "Pacing value"
},
"startDate" : {
"type" : "string",
"format" : "date-time",
"description" : "Campaign start date and time",
"minLength" : 20,
"maxLength" : 29,
"o:queryable" : true,
"o:sortable" : true
},
"endDate" : {
"type" : "string",
"format" : "date-time",
"description" : "Campaign end date and time",
"minLength" : 20,
"maxLength" : 29,
"o:queryable" : true,
"o:sortable" : true
},
"activated" : {
"type" : "boolean",
"default" : false,
"description" : "Flag showing if campaign is activated or not"
},
"includeTopNodes" : {
"type" : "boolean",
"default" : true,
"description" : "Flag showing top nodes should be included or not"
},
"pacingType" : {
"enum" : [ "noRestriction", "budgetPerDay", "budgetPerCampaignLifetime", "stampsPerDay", "stampsPerCampaignLifetime", "cpm", "alwaysOn" ],
"description" : "Pacing type of the campaign"
},
"categoryTransferMethod" : {
"type" : "integer",
"default" : 0,
"description" : "Pacing value"
},
"httpsPull" : {
"default" : false,
"type" : "boolean",
"description" : "Flag for httpsPull"
},
"negativeRevenue" : {
"default" : false,
"type" : "boolean",
"description" : "Flag for negative revenue"
},
"targetingSource" : {
"default" : "user",
"type" : "string",
"description" : "Targeting source"
},
"winFrequency" : {
"type" : "integer",
"default" : 30,
"description" : "Win Frequency"
},
"campaignType" : {
"enum" : [ "normal", "blanket" ],
"description" : "Campaign Type"
},
"revenueRecognition" : {
"type" : "boolean",
"default" : false,
"description" : "Flag for revenue recognition",
"o:queryable" : true
},
"testCampaign" : {
"type" : "boolean",
"default" : false,
"description" : "Flag for test campaign",
"o:queryable" : true
},
"idSwap" : {
"type" : "boolean",
"default" : false,
"description" : "Flag for ID swap",
"o:queryable" : true
},
"jsonPullMacro" : {
"type" : "boolean",
"default" : false,
"description" : "Flag for JSON Pull Macro"
},
"pricingModel" : {
"type" : "object",
"description" : "This schema describes inner structure of a stub resource with id and name",
"additionalProperties" : false,
"properties" : {
"id" : {
"type" : "integer",
"description" : "Reference ID within a resource collection",
"minimum" : 1
},
"name" : {
"type" : "string",
"description" : "Name of the Resource",
"minLength" : 1
}
}
},
"solutionType" : {
"type" : "object",
"description" : "This schema describes inner structure of a stub resource with id and name",
"additionalProperties" : false,
"properties" : {
"id" : {
"type" : "integer",
"description" : "Reference ID within a resource collection",
"minimum" : 1
},
"name" : {
"type" : "string",
"description" : "Name of the Resource",
"minLength" : 1
}
}
},
"notes" : {
"type" : "string",
"description" : "Notes"
},
"recency" : {
"type" : "integer",
"description" : "Recency",
"default" : -1
},
"retargetingSites" : {
"type" : "array",
"items" : {
"$ref" : "#stub"
}
},
"privateSellers" : {
"type" : "array",
"items" : {
"$ref" : "#stub"
}
},
"status" : {
"enum" : [ "idle", "active", "hidden", "archived", "creating", "mapping", "simulating", "simulated" ],
"default" : "idle",
"description" : "Campaign status",
"o:queryable" : true,
"o:sortable" : true
},
"createdAt" : {
"type" : "string",
"format" : "date-time",
"description" : "Campaign created date and time",
"minLength" : 20,
"maxLength" : 25,
"o:queryable" : true,
"o:sortable" : true
},
"updatedAt" : {
"type" : "string",
"format" : "date-time",
"description" : "Campaign updated date and time",
"minLength" : 20,
"maxLength" : 25,
"o:queryable" : true,
"o:sortable" : true
},
"labels" : {
"type" : "array",
"uniqueItems" : true,
"items" : {
"type" : "string"
}
},
"pixelUrls" : {
"type" : "array",
"items" : {
"$ref" : "#pixelUrl"
}
},
"deliveryIDs" : {
"type" : "array",
"description" : "Delivery Id Types used in this Campaign",
"items" : {
"$ref" : "#idType"
},
"o:queryable" : true
},
"prior7DaysDeliveryStat" : {
"type" : "array",
"items" : {
"type" : "integer"
}
},
"priority" : {
"type" : "integer",
"description" : "priority",
"default" : 10
},
"partnerSitesOnly" : {
"type" : "boolean",
"default" : false
},
"winOnSites" : {
"type" : "array",
"items" : {
"$ref" : "#stub"
}
},
"simulationAccuracy" : {
"type" : "integer",
"description" : "Setting for simulating campaign"
}
},
"required" : [ "name", "startDate", "campaignType", "audience" ],
"links" : [ {
"rel" : "search",
"href" : "#",
"schema" : {
"type" : "object",
"properties" : {
"nameOrId" : {
"type" : "string",
"description" : "Filter by Name or ID"
},
"label" : {
"type" : "string",
"description" : "Filter by label"
},
"since" : {
"type" : "string",
"format" : "date-time"
},
"until" : {
"type" : "string",
"format" : "date-time"
},
"q" : {
"type" : "string",
"format" : "scim"
},
"vendorId" : {
"type" : "integer",
"description" : "Filter by vendorId"
},
"onRampFlag" : {
"type" : "boolean",
"description" : "onramp flag"
},
"createdBy" : {
"type" : "integer",
"description" : "Filter by creator user ID"
},
"appId" : {
"type" : "integer",
"description" : "Search campaigns that use specified app ID"
},
"deliveryIDs" : {
"type" : "array",
"description" : "Delivery Id Types that used in this campaign",
"items" : {
"$ref" : "#idType"
}
}
}
}
}, {
"rel" : "canonical",
"href" : "/rest/campaigns/{id}"
}, {
"rel" : "collection",
"href" : "/rest/campaigns"
} ]
}
Related API calls
Here are the API calls you will typically make before you use the campaigns API:
| Before campaigns API | Use case |
|---|---|
| Audiences API | Select the categories you want to include in your audience for targeting, modeling, optimization, or analysis. |
| Categories API | View the first-party and third-party categories that you can use to create your audience. |
List campaigns
You can combine various query parameters to request a filtered set of campaigns. For example, to view all of the campaigns that you created in a specific partner seat, specify your user ID in the createdBy query parameter for the desired pid as shown in the following GET example:
services.bluekai.com/rest/campaigns?createdBy=56789&pid=9876
Sample list response:
Expand to see sample
{
"items" : [ {
"id" : 131691,
"name" : "Holiday Shopper Campaign",
"partner" : {
"id" : 9876,
"name" : "Example Marketing"
},
"audience" : {
"id" : 179743,
"name" : "Holiday Shopper Audience"
},
"bid" : 0.1,
"pacingGoal" : 0.0,
"startDate" : "2017-02-14T00:00:00-06:00",
"activated" : true,
"includeTopNodes" : false,
"pacingType" : "noRestriction",
"categoryTransferMethod" : 2,
"httpsPull" : false,
"negativeRevenue" : false,
"targetingSource" : "user",
"winFrequency" : 0,
"campaignType" : "normal",
"revenueRecognition" : false,
"testCampaign" : false,
"idSwap" : false,
"jsonPullMacro" : true,
"pricingModel" : {
"id" : 2,
"name" : "CPM"
},
"solutionType" : {
"id" : 3,
"name" : "Site Optimization"
},
"recency" : -1,
"retargetingSites" : [ ],
"privateSellers" : [ ],
"status" : "active",
"createdAt" : "2017-02-14T10:24:04-06:00",
"updatedAt" : "2017-02-14T10:24:15-06:00",
"labels" : [ ],
"pixelUrls" : [ ],
"deliveryIDs" : [ {
"id" : 6,
"name" : "Google Advertising ID (AdID)",
"partner" : {
"id" : 0
},
"category" : {
"id" : 489904
},
"id_key" : "adid",
"ingest_key" : "adid",
"super_space" : 3,
"sub_space" : 1,
"permission" : "public",
"id_class" : "primary",
"retention" : 100,
"ingest_methods" : [ "url_argument" ],
"usages" : [ "delivery", "matching", "storage", "opt_out" ],
"device_group" : "mobile",
"context_group" : "app",
"metadata" : [ ],
"sites" : [ 0, 26023, 26024, 33482, 41944 ],
"target_partners" : [ ],
"permissioned_partners" : [ ],
"description" : "Target users whose data was collected from Android apps and are linked to an ADID.",
"status" : "active"
}, {
"id" : 3,
"name" : "Oracle Data Cloud Mobile Cookie ID",
"partner" : {
"id" : 0
},
"category" : {
"id" : 489902
},
"id_key" : "bkmobileid",
"ingest_key" : "bkmobileid",
"super_space" : 0,
"sub_space" : 32451,
"permission" : "public",
"id_class" : "primary",
"retention" : 45,
"ingest_methods" : [ ],
"usages" : [ "delivery", "matching", "storage" ],
"device_group" : "mobile",
"context_group" : "web",
"metadata" : [ ],
"sites" : [ ],
"target_partners" : [ ],
"permissioned_partners" : [ ],
"description" : "Target users whose data was collected from mobile web browsers and are linked to Oracle Data Cloud third-party mobile cookie ID.",
"status" : "active"
}, {
"id" : 9,
"name" : "Apple IDFA",
"partner" : {
"id" : 0
},
"category" : {
"id" : 489903
},
"id_key" : "idfa",
"ingest_key" : "idfa",
"super_space" : 3,
"sub_space" : 4,
"permission" : "public",
"id_class" : "primary",
"retention" : 100,
"ingest_methods" : [ "url_argument" ],
"usages" : [ "delivery", "matching", "storage", "opt_out" ],
"device_group" : "mobile",
"context_group" : "app",
"metadata" : [ ],
"sites" : [ 0, 26023, 26024, 33482, 41944 ],
"target_partners" : [ ],
"permissioned_partners" : [ ],
"description" : "Target users whose data was collected from iOS apps and are linked to an IDFA.",
"status" : "active"
},
{
"id" : 1,
"name" : "Oracle Data Cloud 3rd Party Desktop Cookie ID",
"partner" : {
"id" : 0
},
"category" : {
"id" : 489900
},
"id_key" : "bkuuid",
"ingest_key" : "bkuuid",
"super_space" : 0,
"sub_space" : 0,
"permission" : "public",
"id_class" : "primary",
"retention" : 45,
"ingest_methods" : [ "header" ],
"usages" : [ "delivery", "matching", "storage" ],
"device_group" : "desktop",
"context_group" : "web",
"metadata" : [ "collision", "single" ],
"sites" : [ ],
"target_partners" : [ ],
"permissioned_partners" : [ ],
"description" : "Target users whose data was collected from desktop web browsers and are linked to Oracle Data Cloud third-party cookie IDs.",
"status" : "active"
} ],
"prior7DaysDeliveryStat" : [ ],
"priority" : 1,
"partnerSitesOnly" : false,
"winOnSites" : [ ]
} ],
"totalResults" : 1,
"limit" : 50,
"offset" : 0,
"count" : 1,
"hasMore" : false
}
Query parameters
The campaigns API supports following query parameters:
| Parameter | Type | Description |
|---|---|---|
appId
|
integer | Filter for campaigns that use a specific app template (vendor template). This enables you to return all campaigns from a specifc app partner when you have installed their app multiple times. |
createdBy
|
integer | Filter for campaigns that were created by the Oracle Data Cloud platform user with the specified ID. |
deliveryIDs
|
array |
Filter by the delivery ID types that are used in the campaigns. |
label
|
string | Filter for campaigns that use the specified label. Example: &label=valentines |
nameOrId
|
string | Filter by the campaign's name or ID. |
offset
|
integer | The starting index from which to return the campaigns |
onRampFlag
|
boolean | Filter for OnRamp campaigns. |
q
|
string | Filter the returned campaigns according to the following properties, operators, and a string within double quotes:
Valid operators include:
Depending on the context from where you issue the query that contains the filter expression, you may need to use
percent encoding. For example, if you execute a query as a cURL command, then the filter expression must replace white spaces with |
since
|
string | Filter campaigns updated since the specified date and time in UTC format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'. Use this property in conjunction with the until property to return campaigns within a date and time range. Example:?since=2016-11-01T22:00:00&until=2017-01-30T10:00:00 |
size
|
integer | The maximum number of campaigns to be included in the response. The size property must be used in conjunction with the offset property. |
until
|
string | Filter campaigns updated before the specified date and time in UTC format. |
vendorId
|
integer | Filter by the ID of an installed app (vendor). This us useful for returning all campaigns that use the same app instance. |
GET and POST response summary
The campaigns API GET and POST responses include the following information with each campaign returned:
| Property | Type | Description |
|---|---|---|
activated
|
boolean | Indicates whether the campaign has never had a status of active. If this flag is set to false (the default), the campaign was created but was never activated and has thus been archived. |
audience
|
object | (Required) An object describing the audience for which the campaign is delivering data, including its unique ID and user-specified name |
bid
|
number | If your campaign is using the CPS (cost per impressions) pricing model, bid indicates the maximum bid price for the data to be purchased by your campaign.
If your campaign is using the CPM or FlatFee pricing models, this is the priority rank expressed in hundredths (for example, if the campaign has a priority rank of 6, this value will be 0.06). |
campaignType
|
string | (Required) Determines how your campaign wins based on the categories in the user profile. This can be one of the following values:
|
categoryTransferMethod
|
integer | Specifies how frequently a category is delivered to the partner. This may be one of the following
values:
|
count
|
integer | The total number of campaigns returned by the GET (list) request |
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-04-18T17:46:32-05:00 |
deliveryIDs
|
array | An array describing the delivery IDs used in the campaign. The URI for the deliveryIDs schema is:services.bluekai.com/rest/idType.schema |
endDate
|
date | A timestamp, in yyyy-MM-dd format, indicating when the campaign is scheduled to end. |
httpsPull
|
boolean | Indicates whether the campaign is being sent via a pull pixel using HTTP/SSL (true) or not (false). |
id
|
integer | The unique identifier assigned to the campaign |
idSwap
|
boolean | (Oracle internal use only) Indicates whether the campaign is being sent via SDT (true), or not (false) |
includeTopNodes
|
boolean | If the campaignType is blanket, includeTopNodes indicates whether the blanket campaign includes or excludes the selected category:
|
jsonPullMacro
|
boolean | Indicates whether the campaign is being sent via the JSON returntag method. |
labels
|
array | The list of user-specified labels (strings) for the campaign |
name
|
string | (Required) A string specifying a name for the campaign |
negativeRevenue
|
boolean | This flag is used with some campaign scenarios
to zero out revenue (true), such as for test campaigns or ID-swap campaigns. The default value is false. |
notes
|
string | Any user-specified notes entered for this for this campaign |
pacingGoal
|
number | The maximum amount of money or impressions to be spent or won by your campaign |
pacingType
|
string | The type of pacing to be used for the campaign. Pacing enables you to limit the data purchased by your campaign to a specific daily or campaign lifetime budget. When a campaign reaches this budget, it will stop running. This may be one of the following values:
|
partner
|
object | An object including the name and ID of the DMP partner that shared this campaign with you. This property is only returned if you do not own the campaign. |
partnerSitesOnly
|
boolean | Indicates whether the campaign can win only on partner sites (true). The default value is false. |
pixelURLs
|
array | Describes the campaign's pixel URL, which specifies the destination URL and other details. The URI for the pixelURLs schema is:services.bluekai.com/rest/pixelUrl.schema |
pricingModel
|
object | An object describing the pricing model used by the campaign. This may be one of the following id values:
|
prior7DaysDeliveryStat
|
array | This property is deprecated and should not be used. |
priority
|
integer | A ranking from 1 (lowest priority) to 100 (highest) to decrease or increase its priority among all your campaigns for winning auctions. For example, a campaign with a rank of 20 has a higher priority than a campaign with a rank of 10. The default value is 10. |
privateSellers
|
array | An array describing any private sellers associated with the campaign, such as their name and unique ID |
recency
|
integer | The maximum number of days users must have been tagged with a category attribute to be included in your audience
|
retargetingSites
|
array | An array that indicates whether your audience includes only third-party data for retargeting |
revenueRecognition
|
boolean | (Oracle internal use only) This flag indicates whether the campaign is being used for audience-only campaigns. The default value is false. |
simulationAccuracy
|
integer | (For future use) The accuracy level (expressed as a percentage) to be used for campaign simulation when the status property has a value of simulating |
solutionType
|
object | An object describing the campaign solution type. Its id parameter may be one of the following values:
|
startDate
|
date | (Required) A timestamp, in yyyy-MM-dd format, indicating when the campaign is scheduled to start. |
status
|
string | The current
status of the campaign, which may be one of the following values:
|
targetingSource
|
string | Specifies whether the campaign uses site or user targeting:
|
testCampaign
|
boolean | (Oracle internal use only) If this flag is set to true, the campaign is being used internally for testing. The default value is false. |
updatedAt
|
date | A timestamp in ISO 8601 date and time format (yyyy-MM-dd'T'HH:mm:ssZ) indicating when the campaign was updated
For example: 2017-02-14T10:24:15-06:00 |
winFrequency
|
integer | Specifies how often (in days) your campaign is eligible to win a user in your target audience when they are tagged with a category.
The default value is 30, which means that your campaign may win only when a user is tagged with a new category and does not win if the user is tagged with an existing category.
If this value is set to 0, your campaign is eligible to win each time a user in your target audience is tagged with a new or an existing category. |
winOnSites
|
array | An array that includes the ID and name values of sites on which the campaign can win. If the array is empty, the campaign can win on all sites. |
Response errors
For the most up-to-date list of error messages, call https://services.bluekai.com/rest/campaigns.errors?bkuid=bkUserID&bksig=bksignedString
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-41001 | Campaign was not found |
| BK-41002 | Invalid audience |
| BK-41003 | Invalid solution type |
| BK-41004 | Invalid pricing model |
| BK-41005 | Invalid retargeting site |
| BK-41006 | Invalid private seller |
| BK-41006 | Invalid order |
| BK-41007 | Invalid status for campaign creation |
| BK-41008 | Invalid start date |
| BK-41009 | Campaign has missing fields |
| BK-41010 | Invalid pacing type |
| BK-41011 | Invalid end date |
| BK-41012 | Invalid private sellers |
| BK-41013 | Error processing vendor clients |
| BK-41014 | Prospecting and retargeting cannot both be false |
| BK-41015 | Invalid retargeting sites |
| BK-41016 | Cannot modify field |
| BK-41017 | Invalid category transfer type |
| BK-41018 | Cannot activate campaign with missing field |
| BK-41019 | Cannot activate campaign with zero budget |
| BK-41020 | Campaign cannot return json with pixels |
| BK-41021 | Audience contains third party data. Partner cannot deliver third party data. |
| BK-41022 | Pixel URL contains invalid vendor id |
| BK-41023 | Audience contains third party data. App is not allowed to use third party data. |
| BK-41024 | Audience contains 1st or 2nd party data. App is not allowed to use 1st or 2nd party data. |