Oracle Data Cloud Platform API Developer Guide
The Oracle Data Cloud APIs are RESTful web services that use standard HTTP methods for transferring JavaScript Object Notation (JSON) data between the Oracle Data Cloud platform and your application. The following sections list the Oracle Data Cloud APIs and summarize the HTTP methods and JSON data types they support.
To get started with the Oracle Data Cloud APIs, get your Oracle Data Cloud API keys, learn how to use the interactive API docs, and then click the APIs listed in the table below to learn how to use them for your integration with the Oracle Data Cloud platform.
Note: Oracle Data Cloud tags and code include references to BlueKai and bk. These references are the result of legacy naming policies.
APIs
The Oracle Data Cloud platform provides the following APIs for programmatically classifying your ingested user data, analyzing it, sharing it, and delivering it out to your system and to media execution platforms:
| API | Description | Service URI |
|---|---|---|
| Audiences | View the categories in an audience. Select the first-, second-, and third-party categories you want to target, model, optimize, or analyze. | services.bluekai.com/Services/WS/audiences |
| Audience Discovery Report | Retrieve a list of categories that correlate to a predefined audience–composed of individual categories in segments. | services.bluekai.com/Services/WS/WSMultiAudience |
| Audience grant | Share your audience with DMP partners. | services.bluekai.com/Services/WS/AudienceGrant |
| Bulk ingest | Batch many calls to the user data API in the body of a single HTTPS POST. | bulkapi.bluekai.com/2/api |
| Campaigns | Create instructions for delivering your target audience to DMP partners. | services.bluekai.com/rest/campaigns |
| Categories | Add first-party categories to your taxonomy.View first- and third-party categories that you can use to create your target audiences. | taxonomy.bluekai.com/taxonomy/categories |
| Containers | Create a container for passing site data or unique user IDs (UUIDs) to the Oracle Data Cloud platform. | services.bluekai.com/Services/WS/sites |
| Countries | List the countries supported by the Oracle Data Cloud platform and pass them to the audiences and inventory reach APIs. | services.bluekai.com/rest/countries |
| ID types | Get information about category ID sources and create and manage ID types for your partner seat. | services.bluekai.com/rest/idTypes |
| OnRamp | Ingest and activate your CRM data in the Oracle Data Cloud platform. | portal.datalogix.com/audience-onramp/api/v1/audiences |
| Ping | Verify that your API keys can be used to send authenticated message requests to the Oracle Data Cloud platform. | services.bluekai.com/Services/WS/Ping |
| Rules API | Independently create classification rules that map the user data collected from your site with your categories. | services.bluekai.com/rest/taxonomyRuleChains |
| Schedules | Provide instructions for firing tags. | services.bluekai.com/rest/schedules |
| Segment reach | Get the estimated number of unique users in categories, segments, and audiences. | services.bluekai.com/Services/WS/SegmentInventory |
| Independently add first-party categories to your private taxonomy. | services.bluekai.com/Services/WS/classificationCategories | |
| Independently create classification rules that map the user data collected from your site with your categories. | services.bluekai.com/Services/WS/classificationRules | |
| View the first- and third-party categories that you can use to create your target audiences. | services.bluekai.com/Services/WS/Taxonomy | |
| Taxonomy partner permissions | Whitelist (share) or blacklist (withhold) first-party categories in your private taxonomy with specific buyers. | taxonomy.bluekai.com/taxonomy/partnerPermissions |
| User data | Transfer data into the Oracle Data Cloud platform and deliver data out to your profile store using a server-side API. | api.tags.bluekai.com/getdata/siteID/v1.2 |
| Vendors | Configure a vendor's app to connect your DMP with the app partner's platform in order to ingest and activate data. | services.bluekai.com/rest/vendors |
Supported data formats
The Oracle Data Cloud APIs support JSON-formatted data exclusively:
headers = {"Accept":"application/json","Content-type":"application/json","User_Agent":"Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US; rv:1.9.1) Gecko/20090624 Firefox/3.5"}
Limit of ten calls per second
There is a limit of ten calls per second for each API. Exceeding this number may result in errors.
URLs
The base URL for most Oracle Data Cloud APIs is https://services.bluekai.com/Services/WS
The resource name for the API is then appended to the URL. For example, the URL for the audiences API is https://services.bluekai.com/Services/WS/audiences
Important! You must send calls via HTTPS. Calls using non-secure HTTP result in a 403 Forbidden error.
HTTP methods
The Oracle Data Cloud API supports the GET, POST, PUT, and DELETE methods for retrieving, reading, creating, editing, and deleting objects and collections. The POST and PUT methods require specific JSON-formatted data to be included in the body of the request. The following table summarizes the syntax for calling the Oracle Data Cloud APIs:
| Method | Description | URI |
|---|---|---|
| GET (List) | Retrieve a collection of items. | https://services.bluekai.com/Services/WS/resourceName |
| GET (Read) | Read a specific item. | https://services.bluekai.com/Services/WS/resourceName/?itemId=item_id |
| POST | Create a new item. | https://services.bluekai.com/Services/WS/resourceName (with the required JSON-formatted body) |
| PUT | Edit an existing item. | https://services.bluekai.com/Services/WS/resourceName (with the required JSON-formatted body) |
| DELETE | Delete an item. | https://services.bluekai.com/Services/WS/resourceName/?itemId=item_id |
JSON data
All POST and PUT requests require JSON-formatted data in the body to create or update an object. The JSON format uses human-readable text to send data objects in the form of key-value pairs. The standard JSON data types consist of strings, integers, booleans, objects, arrays, and null values.
Response codes
All Oracle Data Cloud API calls return JSON-formatted data. When a call is successful, the JSON response have a status code of 200 and a msg field set to OK. The POST and PUT responses include the ID of the object returned by the API request.
Error messages
If you send an invalid request to an Oracle Data Cloud API, the JSON response will include status and msg fields describing the error.