Bulk API

The bulk API programmatically onboards large volumes of user data into the Oracle Data Cloud platform. It allows you to batch many calls to the user data API in the body of a single HTTPS POST. Compared to making a large number of individual calls to the user data API, the bulk API reduces latency and maximizes throughput. User data sent via the bulk API is typically onboarded within 24 hours.

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.

Prerequisites

  • Setup: To set up the bulk API for your partner seat, contact My Oracle Support (MOS) and request it. Specify the maximum number of subrequests per day and any custom requirements. You will need to provide your API key.
  • API keys: All calls to Oracle Data Cloud web services must be authenticated using your API keys.
  • User data API calls: To use the bulk API, you should already be familiar with the user data API.
  • HTTPS: All bulk API requests must use HTTPS. The Oracle Data Cloud platform does not support HTTP for bulk API calls.

In this topic  

Service URI

https://bulkapi.bluekai.com/2/api

Message signature

You must generate a message signature (bksig) for the whole POST request.

You do not need to generate an API signature for each individual subrequest (URIPath) in the request body.

bksig is the Base64-encoded string of the output from the HMAC-SHA256 signature algorithm:

HMAC-SHA256(Secret key, POST_DATA)

POST_DATA refers to the request body.

Syntax

https://bulkapi.bluekai.com/2/api?bksig=signature

Example

https://bulkapi.bluekai.com/2/api?bksig=WFbm8mV+iFFimSXlbGb2YetEEsVe8n1IQTLUDVgQRpk%3D

Headers

Calls to the bulk API must include the following headers:

  • "ApiKey" : "APIKey"
  • "Accept" : "application/json"
  • "Content-Type" : "application/json"

Request body

The request body of a bulk API request is expressed in JSON format with a set of subrequests within the Scatter object as shown in the following example. Each subrequest is essentially a user data API call.

{
	"ResponseType": "Detail",
	"Method": "POST",
	"ResponseCallbackUrl": "https://example.com/uri",
	"Scatter": [{
		"Method": "POST",
		"URIPath": "/getdata/12345/v1.2?bkuid=bkUID&phint=filter%3DcampId1&idfa=IDFA",
		"RequestID": "123ABC"
	}, {
		"Method": "POST",
		"URIPath": "/getdata/12345/v1.2?bkuid=bkUID&phint=filter%3DcampId1&idfa=IDFA",
		"RequestID": "234BCD"
    },
    . . .
  ]
}

Request properties for the main request

Property Type Description
Method string Specifies the HTTP verb for the subrequest, such as GET or POST
ResponseCallbackUrl string (Recommended) Specify a fully-qualified URL to which the response will be sent once it is processed. If specified, the original bulk API request connection is closed immediately after the request is received.

If the callback server URI fails, the bulk API does not retry sending the response via the callback URL.

Important: If you set this property to an empty or null value, the response will be streamed back on the same connection as the bulk API request and your connection will wait for all subrequests to be processed. This is not recommend for production, because a request exceeding 2,000 subrequests may result in a connection reset error while waiting for a response.
ResponseType string Specify the level of detail in the response to the bulk API request:
  • Detail: Include a detailed JSON response body is sent for each subrequest in addition to an initial 200 response for the main request. Responses become available when the corresponding request completes, which may not be in the same order that they are sent. If a RequestID is included in each subrequest, they will be included in the corresponding responses.
  • None: A single 200 response will be sent for the entire bulk request. No details will be sent for subrequests.
  • Summary: Include the status (200, 404, or other HTTP codes), the number of requests, and a comma-delimited list of RequestIDs for all subrequests.
Scatter object An object that describes a batch of HTTP subrequests

Subrequest properties (below Scatter)

Property Type Description
Method string Specifies the HTTP verb for the subrequest, such as GET or POST
RequestID string (Recommended) The unique identifier of the subrequest for traceability, correlating each subrequest with its response, and tracking the status of each subrequest. You can use a cookie ID for the RequestID value or generate another unique string.

The subrequests might not be returned in the same order as they were sent, so specifying a RequestID value can help you to parse the subresponses and correlate them with their subrequests.
URIPath string The URL path of the subrequest's call to the user data API

 

{
	"BulkHost": "bulkapi.bluekai.com",
	"Gather": [{
		"RequestID": "123ABC",
		"Body": {
			"categories": [],
			"userid": "XYZ123",
			"msg": "ok",
			"status": 200
		}
	}, {
		"RequestID": "234BCD",
		"Body": {
			"categories": [],
			"userid": "ABC456",
			"msg": "ok",
			"status": 200
		}
	}, {
		"RequestID": "345CDE",
		"Body": {
			"status": 499
		}
	}]
}
{
	"BulkHost": "bulkapi.bluekai.com",
	"Gather": [{
		"Status": 200,
		"NumberOfRequests": 2,
		"RequestIDs": ["1461841582583", "1461841582100"]
	}, {
		"Status": 404,
		"NumberOfRequests": 1,
		"RequestIDs": ["1461841582873"]
	}, {
		"Status": 499,
		"NumberOfRequests": 1,
		"RequestIDs": ["1461841582190"]
	}]
}
{
	"BulkHost": "bulkapi.bluekai.com",
	"Gather": []
}

Limits

  • The maximum size of any batch POST request is 100 MB.
  • The maximum number of subrequests per batch call is 500,000.

Multiple Calls on the Same User. If you are passing multiple User Data API calls on the same user, seprarate the calls in your batch file so they're not made consecutively, or consolidate them into a single call. Making consecutive calls on the same user may cause a race condition that prevents one or more calls from appending data to the user's profile.

Response codes

If there is a problem with your main bulk API request, the response will use one of the following:

Code Message
400 Bad Request: invalid API key, invalid JSON, or the request does not contain required properties
401 Unauthorized (invalid signature or no signature present)
402 Payment Required (daily limit exceeded)
403 Forbidden (number of subrequests does not meet "minimum sub-requests per batch")
404 Not Found
405 Method Not Allowed (invalid request: invalid HTTP method)
411 Length Required (post request body has 0 size)
413 Payload Too Large (maximum number of subrequests exceeded)
500 Internal Server Error: This can indicate standard error or that something wrong with bulk service, such as a POST larger than 100 MB.

Note: These response codes are for the main bulk API request. By default, the platform retries each subrequest up to three times but does not log failed calls. You can determine the status of each subrequest by reviewing the corresponding subresponse (if the ResponseType property is set to Detail or Summary). A final status code of 200 or 404 is reported for each subrequest in the Status value of the response body. A special bulk ingest status code of 499 indicates an invalid subrequest URI, such as a URIPath value that includes a space character or does not begin with /getdata/.
For details about subrequest errors, see user data API error responses.

SLA 

User data sent via the bulk API is typically onboarded within 24 hours.

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

Learn more

User data API

Authentication