User Data API
You use the User Data API to programmatically onboard user data into the Oracle Data Cloud platform and to deliver it back out to your site. The User Data API functions as an always-on pipe between your offline data, your taxonomy, and your website and mobile apps.
You can also use the User Data API to retrieve information about which categories your users have been classified into. You can use this information to satisfy privacy-related requests from users.
EU Data. To ingest and receive data for user profiles located in the European Union (EU), you must have signed Oracle's General Data Protection Regulation (GDPR) agreements. Contact your Oracle Account Representative to obtain and sign the agreements.
The User Data API supports one call per user with a maximum of 1,000 calls per second. You must make separate API calls on each user for whom you want to ingest or deliver data. You can use the Bulk API to batch individual User Data API calls in the body of a single HTTPS POST request. Using the Bulk API reduces latency and maximizes throughput. Contact My Oracle Support (MOS) to request access to the Bulk API. In the request, include the maximum number of subrequests per day and any custom requirements. A MOS specialist will enable your web service keys for making Bulk API calls.
User Data API responses are typically delivered within 300 ms if your API request is made from the US, and between 500-600 ms from outside the US.
In this topic
API reference
The embedded reference doc below 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 document in a three-pane format.
For help with this API, contact My Oracle Support (MOS).
Base path
https://api.tags.bluekai.com/getdata/siteID/v1.2/...
Supported ID types
The data you onboard and deliver can be linked to any of several ID types described in the following table.
| ID Type | Parameter | ID Space | Description |
|---|---|---|---|
| BKUUID | userid
|
Primary ID (desktop and mobile web) | The obfuscated Oracle Data Cloud unique user ID (BKUUID) that you received via an ID swap, SDT delivery, or JSON Return tag. |
| PUUID |
Secondary ID (linked to BKUUID; desktop and mobile web)
|
Your partner-based unique user ID (PUUID), which may be an email hash, account ID hash, cookie ID, or other identifier. The PUUIDs you pass must be ID swapped to BKUUIDs or you get 404 "user not found" errors. See ID Swapping for more information. The site ID you include in your User Data API calls must be enabled for passing PUUIDs or you get a 404 "user not found" error. To do this, open a MOS ticket requesting "puserid access for the User Data API" and include your partner name, partner ID, your ID swap site ID, and the site ID you are passing in your User Data API calls. If you are passing PUUIDs that have been ID swapped via phints (for example, you use the Oracle Data Cloud core tag to execute ID swaps), you must pass the key in the See ID Swapping for more information on setting up the ID sync. |
|
| MAID | adid
idfa
|
Primary ID, mobile app | Passing the adid or idfa enables you to send and get the data linked to this mobile advertising ID, which operates in a primary ID space (the data you are sending or getting is not linked to a BKUUID). Country Identification Method: When you onboard data linked to a MAID, you should pass a country code in the User Data API call to specify users' country locations. However, to address scenarios where you cannot identify the user's country, you can specify in the same MOS ticket one of the following methods for classifying users' country locations (if you don't pass a country code and don't select one of these methods, you get a 400 "country code not provided" error):
To request the default or unspecified country method, request "SITES_DEFAULT_CCODE for the User Data API" and include your partner name, partner ID, and classification site ID, and specify either (a) the default country to be used or (b) you want users' country location to be marked as "unspecified". |
Data ingest
With the User Data API, you can independently onboard and activate the user data stored in your data warehouse, CRM database, or any other offline source anytime. This enables you to run models and analytics in your offline source to segment your users, and then import their attributes directly into your taxonomy—whenever you need to. Your user data is instantly added to your taxonomy and ready for activation.
To onboard data, you first need to create a site ID, categories, and rules using the platform UI, or using the Containers (Sites), Categories, and Rules APIs.
Request
You can make User Data API calls to onboard data by sending GET requests to api.tags.bluekai.com/getdata/{siteid}/v1.2?{idType}={userId}&phint={key}={value}&bkuid={Web Service Key}&bksig={Method Signature} with the following components:
- Site ID. The site ID you created and included in your rules.
- ID Type and User ID . The ID type [BKUUID (userid), PUUID (puserid), or MAID (adid or idfa], and the actual ID. You must pass MAIDs in 8-4-4-4-12 format.
- Phint. A key-value pair representing the user's attributes and behavior, which you included in your rules. The Oracle Data Cloud platform evaluates the site ID and phints in your rules to determine into which categories the user gets added.
- Web Service Key. Your key for making Oracle Data Cloud API calls. To get this, log into your seat. and click Tools>Web Service Key Tool. Click here for more information on getting your Web service keys.
- Method Signature. The request signature (bksig) generated by encrypting the HTTP_METHOD, URI_PATH, QUERY_ARG_VALUES, and POST_DATA into a string byte array, and then signing the resulting string with your Web service private key. Click here for more information on authenticating your User Data API calls.
If you are onboarding data linked to MAIDs or other non-cookie ID types, you must also pass a ccode parameter set to the two-letter ISO 3166-1 alpha-2 country code where the user's data was acquired and set the create_profile flag to 1. This enables a new user profile in your ID space to be added to the Profile Store. If the profile already exists, the user attributes you are passing in the phints parameter are just appended to the user's profile.
The User Data API call for MAIDs therefore has the following syntax: api.tags.bluekai.com/getdata/{siteid}/v1.2?idfa|adid={8-4-4-4-12}&phint={key}={value}&ccode={countryCode}&create_profile=1&bkuid={Web Service Key}&bksig={Method Signature}
See parameters for the descriptions of all the parameters you can include when sending data with the User Data API.
Request Examples
The following examples demonstrate how to make User Data API requests for onboarding data linked to BKUUIDs, PUUIDs, and MAIDs. In each example, site ID 50838 and a purchaser=smartphone phint are being passed into the call.
BKUUID
https://api.tags.bluekai.com/getdata/50838/v1.2?userid=3PR/ef6y99YlryOu&phint=purchase=smartphone&bkuid=a3c18b227976ad07da5d679c7259f726631d39cf49252926407dc05c3e8be643&bksig=uBtWOAzM6cduAbEeaQoU6%2BkNUL87%2Brxudio2DC00Y5c%3D
PUUID
https://api.tags.bluekai.com/getdata/58038/v1.2?puserid=z0OgPvTRj990wQs&phint=purchase=smartphone&bkuid=a3c18b227976ad07da5d679c7259f726631d39cf49252926407dc05c3e8be643&bksig=uBtWOAzM6cduAbEeaQoU6%2BkNUL87%2Brxudio2DC00Y5c%3D
MAID
https://api.tags.bluekai.com/getdata/58038/v1.2?adid=6D92078A-8246-4BA4-AE5B-76104861E7DC&phint=purchase=smartphone&ccode=US&create_profile=1&bkuid=a3c18b227976ad07da5d679c7259f726631d39cf49252926407dc05c3e8be643&bksig=uBtWOAzM6cduAbEeaQoU6%2BkNUL87%2Brxudio2DC00Y5c%3D
Response
The User Data API returns a 200 code if the user profile has been found or created. It returns a 404 "user not found" error if the user does not exist or has not been ID synced to a cookie. For successful responses, the User Data API also returns the user ID in some cases:
- If you are onboarding data linked to a BKUUID (userid), the response includes the user's obfuscated BKUUID.
- For data linked to a PUUID, the response includes your PUUID (puserid) for the user and their obfuscated BKUUID.
- For data linked to a MAID, the response does not include the user's idfa or adid.
Response Example
The following example demonstrates the response to a User Data API request for onboarding user data linked to a PUUID:
{
"status": 200,
"msg": "ok",
"userid": "3PR/ef6y99YlryOu",
"puserid": "z0OgPvTRj990wQs",
"categories": []
}
Data delivery
You can use the User Data API to deliver your user data to your website or your internal system. The API can return the category IDs of users being targeted in your audience. which enables you to target customers with optimized site content and ads based on their attributes and behavior.
Delivering data with the User Data API has limitations that you should consider:
- The API call does not retrieve all the historic categories of a user.
- If you use the API for data associated with a PUUID, the call does not retrieve all profiles linked to the PUUID. It retrieves only the profile that was created first.
- If the API container is configured to update all IDs linked to a PUUID, a call to retrieve user information does not return any profiles.
To deliver data, you must first create and deliver audiences by using the platform UI, or by using the Audiences and Campaigns APIs. When you configure data delivery, specify JSON return as the delivery method and specify the same site ID that you use in User Data API calls.
Request
You can make User Data API calls to deliver data by sending GET requests to
api.tags.bluekai.com/getdata/{siteid}/v1.2?{idType}={userId}&bkuid={Web Service Key}&bksig={Method Signature}
with the following components:
- Site ID. The site ID you created and included in your rules.
- ID Type and User ID . The ID type [BKUUID (userid), PUUID (puserid), or MAID (adid or idfa], and the actual ID.
- Web Service Key. Your key for making Oracle Data Cloud API calls.
- Method Signature. The generated request signature.
See the API reference document for descriptions of all the parameters you can include when getting data with the User Data API. You can also pass phints in the request to onboard and deliver data simultaneously.
You can filter the category IDs returned by the User Data API by passing a comma-separated list of campaign IDs in the filterbycampids parameter. This enables the User Data API to only return those categories that have been targeted and won by one or more specific campaigns. By default, the User Data API will return the categories being targeted and won by all campaigns.
Response
The User Data API returns the category IDs that are linked to the user's profiles that are being targeted and delivered, the last time the user was last tagged with the categories, and the number of times they’ve been tagged with the categories. It will return a 404 "user not found" error if the user does not exist or has not been ID synced to a cookie.
The following example demonstrates the response to a User Data API data delivery request:
{
"status": 200,
"msg": "ok",
"userid": "3PR/ef6y99YlryOu",
"categories":
[
{
"id": 1211430,
"count": 3,
"lastmodified": 1520881959
}
]
}
Examples
Sample User Data API response - successful (with categories)
{
"status": 200,
"msg": "ok",
"userid": "<BlueKai_UUID>",
"puserid": "<Partner_UUID>",
"categories": [{
"id": 123,
"count": 1,
"lastmodified": 1342722630
}, {
"id": 323,
"count": 3,
"lastmodified": 1342722400
}]
}
Sample User Data API response - successful (without categories)
{
"status": 200,
"msg": "ok",
"userid": "ABCD",
"puserid": "XYZ123",
"categories": {}
}
Sample User Data API error response
{
"status": 400,
"msg": "user id is empty",
"userid": "",
"puserid": "",
"categories": {}
}
Registry request
You can use the User Data API to find the categories into which your users have been classified. For example, if a user submits a privacy request to learn what data has been collected about them, you can use a GET call to retrieve a list of the categories that apply to them. There is a separate endpoint (api.tags.bluekai.com/getregistrydata) for these registry calls. Use the following syntax:
api.tags.bluekai.com/getregistrydata/{siteID} /v1.2?{idType}={userID}&bkuid={Web Service Key}&bksig= {Method Signature}
with the following components:
- Site ID. The site ID you created and included in your rules.
- ID Type and User ID . The ID type [BKUUID (userid), PUUID (puserid), or MAID (adid or idfa], and the actual ID.
- Web Service Key. Your key for making Oracle Data Cloud API calls.
- Method Signature. The generated request signature.
Response
The User Data API returns the category IDs that are linked to the user's profile.. The following example shows the response to a registry request:
{ {
"status": 200,
"msg": "ok",
"userid": "3PR/ef6y99YlryOu",
"categories": [
{
"id": 1211432,
"name": "5-10%",
"path": "Oracle Modeling 360 - private > ExampleCompany > US Default > Visitors > 5-10%
}
{
"id": 1211434,
"name": "5-10%",
"path": "Oracle Modeling 360 - private > ExampleCompany > US Default > Visitors > 10-15%
}
{
"id": 1211436,
"name": "5-10%",
"path": "Oracle Modeling 360 - private > ExampleCompany > US Default > Visitors > 15-20%
}
]
}
If your User Data API request is successful, a JSON-formatted list is returned including any new qualifying category IDs the user has been tagged with.
Partner Clear
Partner clear will remove all categories for a device for a specific site or all sites associated with a partner ID. When the categories are removed, the profile will no longer be targeted. This call is typically used as a response to a 'Delete my Data' request.
Use the following syntax:
api.tags.bluekai.com/api/v2/users/{id-type}/{id-value}/tags?
with the following components:
id-type: A special value id for partner id ( PUUID) as {id-value}
Other valid definitions are from IdType push, the source field: https://push.bluekai.com/Push/idtype
Examples are:
idfor Partner id (PUUID)bkuuidfor BlueKai's Profile ID (most likely obfuscated)idfaoradidfor MAIDs
The following table summarizes the different HTTP methods and the URL to get the desired function.
| Method | HTTP body | URL | Header | Function |
|---|---|---|---|---|
DELETE
|
empty |
OR
|
X-SiteID:2000
|
Partner Clear - Delete categories for a user in site 2000 (site id in uri arg must be the same as "X-SiteID") |
DELETE
|
empty | api.tags.bluekai.com/api/v2/users/idfa/12345678-1234-1234-1234-123456781234/tags?partner=1000
|
Partner Clear - Delete categories for a user for partnerID 1000 , which means all the sites associated with the partner |
Error response summary
If your User Data API request is not successful, you will receive JSON-formatted data that includes an error code and a message description. The following table describes the error status code and message returned to you in the status and msg fields of the response if your request failed.
| Status code | Message | Version supported |
|---|---|---|
| 200 | "ok" | All |
| 400 | "user id is empty" | All |
| 404 | "user id not found" | All |
| 403 | "invalid site id in the request" | All |
| 400 | "unsupported version of api specified" | All |
| 500 | "internal server error" | All |
| 400 | "invalid bkuid specified in the request" | Version 1.2 |
| 400 | "The bkuid specified does not have access to the site" | Version 1.2 |
| 400 | "signature specified mismatch" | Version 1.2 |
| 400 | "signature specified is empty" | Version 1.2 |
Python code example
The sample Python script demonstrates how to generate the authentication signature, construct the User Data API request URL, and make the HTTP call to the platform.
The following table lists the required fields and syntax for running this script on desktop, mobile, and mobile app users.
Required fields for sample script
| User type | ID type | Fields | Example |
|---|---|---|---|
| Desktop or mobile user | BKUUID | siteid, userid, bkuid, bksecretkey
|
./userDataApi.py -s <siteid> -u <userid> -n <phint> -c <campids> -t <target> -b <bkuid> -k <bksecretkey> |
| Desktop or mobile user | PUUID | siteid, puserid, pfield, bkuid, bksecretkey
|
./userDataApi.py -s <siteid> -p <puserid> -f <pfield>-n <phint> -c <campids> -t <target> -b <bkuid> -k <bksecretkey> |
| Mobile app user | IDFA | siteid, idfa, bkuid, bksecretkey
|
./userDataApi.py -s <siteid> -e <idfa> -n <phint> -c <campids> -t <target> -b <bkuid> -k <bksecretkey> |
| Mobile app user | ADID | siteid, adid, bkuid, bksecretkey
|
./userDataApi.py -s <siteid> -d <adid> -n <phint> -c <campids> -t <target> -b <bkuid> -k <bksecretkey> |
/ userDataApi.py (sample Python script )
import base64
import hashlib
import hmac
import logging
from collections import namedtuple
import argparse
import requests
from requests.models import PreparedRequest
try:
from urllib.parse import urlunparse, urlparse, unquote_plus, parse_qs
except ImportError:
from urlparse import urlunparse, urlparse, parse_qs
from urllib import unquote_plus
logger = logging.getLogger('User Data API')
'''
This script generates signed url by given parameters, and sending get request
the elementary parameters you must supply in are:
siteid, bkuid, bksecretkey, in addition should use at least one of the
next parameters to supply for identify the user for getting or sending data
about:
-userid
-puserid
-adid
-idfa
In addition you can add more optional parameters which let you get/send more
or more specific information by using one of the next options:
*puserid, phint , target, filterbycampids
*puserid must be followed by pfield or be known in advance to Oracle
'''
# the next parameter is tuple of ("arg shortcut name", "arg name", helper")
cmd_args = namedtuple('cmd_args', ['short', 'arg_name', 'helper'])
required_parameters = [
cmd_args("-s", "--siteid",
"The unique site identifier generated when you created your "
"container"),
cmd_args("-b", "--bkuid", "Your web service user key"),
cmd_args("-k", "--bksecretkey", "your web service private key"),
]
optional_parameters = [
cmd_args("-u", "--userid",
"The obfuscated Oracle Data Cloud unique user ID "
"that you received via an ID swap, SDT delivery, or JSON Return "
"tag."),
cmd_args("-p", "--puserid", "Your partner-based unique user ID (PUUID), "
"which may be an email hash, account ID hash, "
"cookie ID, "
"or other identifier.\nThe PUUIDs you pass "
"must be ID swapped "
"to BKUUIDs or you will get 404 user not "
"found errors"),
cmd_args("-f", "--pfield",
"The type of key associated with the partner-based "
"UUID you passed in the puserid field."),
cmd_args("-d", "--adid",
" enables you to send and get the data linked to this "
"mobile advertising ID, which operates in a primary ID "
"space"),
cmd_args("-e", "--idfa",
" enables you to send and get the data linked to this "
"mobile advertising ID, which operates in a primary ID "
"space"),
cmd_args("-c", "--campIds", "A list of comma-delimited campaign IDs"
"This field is used for filtering the "
"categories included in the user data API "
"response based on the specified campaign IDs "
"that have "
"targeted and won the user."),
cmd_args("-t", "--target", "indicate whether the ability to use a set of "
"conditions in a schedule that determine "
"whether a tag is fired"),
]
optional_multiply_parameters = [
cmd_args("-n", "--phint",
" A key-value pair representing the user's attributes "
"and behavior, which you included in your rules")
]
def sign_string(bk_secret_key, str_to_sign):
h = hmac.new(bytes(bk_secret_key.encode('utf-8')), bytes(
str_to_sign.encode('utf-8')),
hashlib.sha256)
return base64.standard_b64encode(h.digest())
def generate_string_to_sign(url, method):
parsed_url = urlparse(url)
query_arr = parse_qs(parsed_url.query)
query_values = ''.join([''.join(v) for v in query_arr.values()])
return method + parsed_url.path + query_values
def get_parsed_args_dict():
parser = argparse.ArgumentParser()
named_required = parser.add_argument_group('required arguments')
named = parser.add_argument_group('extra optional arguments')
named_multiply = parser.add_argument_group('positional multiply arguments')
for current_arg_detail in optional_parameters:
named.add_argument(current_arg_detail.short,
current_arg_detail.arg_name,
help=current_arg_detail.helper)
for current_arg_detail in required_parameters:
named_required.add_argument(current_arg_detail.short,
current_arg_detail.arg_name,
help=current_arg_detail.helper,
required=True)
for current_arg_detail in optional_multiply_parameters:
named_multiply.add_argument(current_arg_detail.short,
current_arg_detail.arg_name,
help=current_arg_detail.helper,
action='append', nargs='*')
args = parser.parse_args()
return vars(args)
def filter_args_dict(args_dict):
return {k: v for k, v in args_dict.items() if v}
def build_url_by_args():
args_in_use = filter_args_dict(get_parsed_args_dict())
# handle special fields which are not related to query part of url
siteid = args_in_use.pop("siteid", None)
bkuid = args_in_use.pop("bkuid", None)
bksecretkey = args_in_use.pop("bksecretkey", None)
url_before_sign = urlunparse(
('https', 'api.tags.bluekai.com', '/getdata/' + siteid + '/v1.2',
None, None, None))
req = PreparedRequest()
req.prepare_url(url_before_sign, args_in_use)
return req.url, bkuid, bksecretkey
def get_signed_url(url_before_sign, bk_uid, bk_secret_key):
if not bk_uid or not bk_secret_key:
raise ValueError('bkuid or bksecretkey are required and missing')
url_before_sign = unquote_plus(url_before_sign)
string_to_sign = generate_string_to_sign(url_before_sign, "GET")
signature = sign_string(bk_secret_key, string_to_sign)
params = {'bkuid': bk_uid, "bksig": signature}
req = PreparedRequest()
req.prepare_url(url_before_sign, params)
return req.url
def do_request(url):
result = requests.get(url)
logger.info("The request you create is\n{}\n".format(url))
raw_data = result.content
logger.info("the request result is:\n {}\n".format(str(raw_data)))
return raw_data
def main():
logging.basicConfig(level=logging.INFO, format='%(name)s - %(levelname)s - %('
'message)s')
print('\nGenerates a signed url using the given arguments and sends a '
'GET request.')
url_by_param, bk_uid, bk_secret_key = build_url_by_args()
signed_url = get_signed_url(url_by_param, bk_uid, bk_secret_key)
do_request(signed_url)
if __name__ == "__main__":
main()