Using the Oracle OnRamp API to Onboard your CRM Data
You can use Oracle's OnRamp API for the on-demand onboarding and activation of your CRM data. The OnRamp API provides an automated, programmatic solution that enables you to maximize match rates and onboard more data, more often, and whenever you want. With the OnRamp API, you can segment the users in your CRM database and then securely make API calls with your customers' personally identifiable information (PII).
OnRamp matches your offline users and then classifies their attributes into new categories in your private taxonomy in your Oracle Data Cloud platform. You can then activate your CRM data across multiple media execution platforms for targeting, analysis, modeling, and optimization.
The OnRamp API provides the following benefits:
- Self-serve onboarding: Upload your PII on demand and include new values to capture new data and customize your taxonomy.
- Programmatic, automated onboarding: Use a quick and automated workflow that reduces the offline onboarding process. The OnRamp API enables you to programmatically import your CRM data and automatically classify it the Oracle Data Cloud platform.
- Maximum match rates: Leverage the platform-DLX cookie overlap in the Oracle ID graph to activate more of your customer base.
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
Requirements
To use the OnRamp API, you must meet the following requirements:
- OnRamp API Keys. You must pass your keys with each call to the OnRamp API. To get your OnRamp API keys, contact your Oracle Data Cloud representative. Your client ID and client secret keys will be delivered in two separate emails.
- PII. To maximize match rates, you should provide as much customer data as possible. To match users, however, you must provide at least one of the following PII combinations:
- First Name, Last Name, Address, City, State, Zip.
- First Name, Last Name, Zip.
- Email Address.
- Hashed Email Address (SHA-256, SHA-1, or MD5).
- Country. You may only onboard CRM data for users residing in the United States. No other countries are currently supported for onboarding.
- OnRamp App. You must access to the OnRamp app in the Oracle Data Cloud platform.
Getting started
Onboarding CRM data with the OnRamp API requires three POST request to create an audience, create segments, and then add users to the segments.
| Step | Description | Endpoint | |
|---|---|---|---|
| 1 | Create audience |
An audience represents the CRM file being uploaded. An audience contains one or segments (classifications of users with the same attributes/behavior). This POST response includes the audience ID needed for the subsequent segments and and users API calls. |
https://portal.datalogix.com/audience-onramp/api/v1/audiences |
| 2 | Create segments | Segments represent the columns in your CRM file that contain specific user classifications (for example, age, gender, coffee/tea drink preference and so on). Segments get mapped to new categories in your DMP taxonomy. | https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/segments |
| 3 | Add users to segments | The PII of the users being added to segments. When you add users to segments, they get classified into the categories in your DMP taxonomy. | https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/users |
Create an Audience
An audience represents the CRM file being uploaded. An audience contains one or segments (classifications of users with the same attributes/behavior).
To create an audience, you make a POST request to https://portal.datalogix.com/audience-onramp/api/v1/audiences that includes a JSON body with the name and description of your audience, and segmentationEnabled set to true. The following example demonstrates the JSON body:
{
"name": "Coffee Drinkers",
"description": "An offline file with the age, gender, and drink preference (coffee or tea) of customers",
"segmentationEnabled": true
}
The POST response will include the unique ID generated for your audience (for example, 12345) and an HTTP 201 success code (audience created successfully).
{
"audienceId": 12345
}
Create segments
Segments represent the columns in your CRM file that contain specific user classifications (for example, age, gender, coffee/tea drink preference and so on). Segments get mapped to new categories in your DMP taxonomy.
To create segments, you make a POST request to https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/segments with the following:
- The audience ID returned when you created the audience (for example, https://portal.datalogix.com/audience-onramp/api/v1/audiences/12345/segments)
- A JSON body that includes a list of segments.
Each segment includes a classificationName and segmentName, which represent key-value pairs. For example, to specify a "gender" segment, you would create two segments: one with a classificationName set to "gender" and segmentName to "female", and another with the classificationName set to "gender" and segmentName to male.
The following example demonstrates a JSON body with age, gender, and drink segments:
{"segments":[
{
"classificationName":"gender",
"segmentName":"female"
},
{
"classificationName":"gender",
"segmentName":"male"
},
{
"classificationName":"age",
"segmentName":"18-35"
},
{
"classificationName":"age",
"segmentName":"35-65"
},
{
"classificationName":"drink",
"segmentName":"coffee"
},
{
"classificationName":"drink",
"segmentName":"tea"
}
]
}
The POST response will include the IDs for the classifications and segments created and an HTTP 201 success code (segments created successfully).
{
"segments":[
{
"classificationId":208900,
"segmentId":208901,
"classificationName":"gender",
"segmentName":"female"
},
{
"classificationId":208902,
"segmentId":208903,
"classificationName":"gender",
"segmentName":"male"
},
{
"classificationId":208904,
"segmentId":208905,
"classificationName":"age",
"segmentName":"18-35"
},
{
"classificationId":208906,
"segmentId":208907,
"classificationName":"age",
"segmentName":"35-65"
},
{
"classificationId":208908,
"segmentId":208909,
"classificationName":"drink",
"segmentName":"coffee"
},
{
"classificationId":208910,
"segmentId":208911,
"classificationName":"drink",
"segmentName":"tea"
}
]
}
Add users to segments
To add users to the segments you created in step 2, you make a POST request to https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/users with (1) the audience ID you got in step 1 in the URI (for example, https://portal.datalogix.com/audience-onramp/api/v1/audiences/12345/users)and (2) a JSON body that includes a list of items. Each item contains the PII of the user, the segments to which they are to be added, and the operation set to "APPEND". At a minimum, the PII may be one of the following combinations:
- First Name, Last Name, Address, City, State, Zip.
- First Name, Last Name, Zip.
- Email Address.
- Hashed Email Address (SHA-256, SHA-1, or MD5).
Maximizing Match Rates. To maximize match rates and onboard as much data as possible, provide all the PII you have on users.
The following example demonstrates a JSON body adding a user to the female, 35-65, and coffee segments created in step 2 based on their address, email address, and SHA-256 email hash:
{
"items":[
{
"operation":"APPEND",
"segments":{"gender":"female", "age":"35-65", "drink":"coffee"},
"firstName":"Joe",
"lastName":"Smith",
"address1":"120 Elm St.",
"address2":"#600",
"city":"San Diego",
"state":"CA",
"zip":"92102",
"email":"joe.smith@yahoo.com",
"emailSha256":"5072c9c307c2b5a7ea4aaac9722fa45cbe3537e98240afaecba88e3071c379bc"
}
]
}
The POST response will include an HTTP 202 success code (user added successfully).
{
"body":{},
"statusCode":"202",
"statusCodeValue":0
}
OnRamp category creation
When you add users to segments, OnRamp creates categories in your Oracle Data Cloud platform taxonomy for each of your segments. It also creates classification rules that onboard the segments into the new categories. After your data has been onboarded, you can find the categories created for your segments under the Self-Classification node in your DMP taxonomy the category names have the following syntax: {Platform category ID}-{DLX Audience Name} (for example, 36524-Smartphone Buyers). You can add your new categories to your target audiences, and create a campaign to deliver your audiences across multiple media execution platforms. You can create audiences and campaigns using the Oracle Data Cloud platform UI or the Oracle Data Cloud platform Audience and Campaign APIs.
Authenticating OnRamp API requests
The API security model is based upon the HMAC (Hash-based Message Authentication Code) used in AWS, Oracle's Cloud Infrastructure, and other public API platforms. The basic algorithm hashes select portions of the HTTP request (the signing string) using a HMAC key known to both the Oracle Data Cloud API Security Gateway and the application. The resulting hashed string (the signature) is then included in the request. Each API request requires certain HTTP headers be included that identify your activity. If these headers are missing, incomplete, or wrong, your request will fail with a HTTP/401 (Forbidden) error.
GET
The request must contain the Host and Date and Authorization headers. While the Host and Date headers are standard the Authorization header must be formatted as such:
3AMP version="1",keyId="<clientId>",headers="(resource-target) host date",algorithm="hmac-sha256", signature="<signature>"
The <clientId> value will be provided to you and the <signature> must be computed for each request using a Base64-encoded, SHA256 hashed value using your client secret as such (NOTE: lowercase):
get<request path><host header value><date header value>
POST
The following headers must be included:
- Host
- Date
- Content-Type
- Content-Length
- X-Content-SHA256 This is the hash of the post body.
The Authorization header is as follows:
3AMP version="1",keyId="<clientId>",headers="(resource-target) host date content-type content-length x-content-sha256",algorithm="hmac-sha256", signature="<signature>"
PUT
This is the same as a POST request.
DELETE
This is the same as a GET request.
Java Example
This section provides an example of how to create the HMAC MD5 signatures in Java:
import org.glassfish.jersey.client.JerseyClientBuilder;
import org.glassfish.jersey.client.ClientConfig;
import javax.ws.rs.client.Client;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Base64;
import java.util.Date;
import java.util.Locale;
import java.util.TimeZone;
public class OnRampApiExample {
private static final String Host = "https://portal.datalogix.com";
private static final String Algorithm = "HmacSHA256";
private static final String GetHeaderFmt = "3AMP version=\"1\",keyId=\"%1$s\",headers=\"(resource-target) host date\",algorithm=\"hmac-sha256\",signature=\"%2$s\"";
private static final String PostHeaderFmt = "3AMP version=\"1\",keyId=\"%1$s\",headers=\"(resource-target) host date x-content-sha256 content-length content-type\",algorithm=\"hmac-sha256\",signature=\"%2$s\"";
private static final String Rfc2822FmtStr = "EEE, dd MMM yyyy HH:mm:ss zzz";
private static final DateFormat Rfc2822Fmt = new SimpleDateFormat(Rfc2822FmtStr, Locale.US);
private static final Mac Hmac;
// Replace these values
private static final String ClientId = "***REDACTED***";
private static final String Secret = "***REDACTED***";
static {
try {
System.setProperty("sun.net.http.allowRestrictedHeaders", "true");
Hmac = Mac.getInstance(Algorithm);
} catch (Exception ex) {
throw new RuntimeException(ex);
}
}
private static void post(String payload, String host, String uri, String clientID, String clientSecret) throws Exception {
Hmac.init( new SecretKeySpec(clientSecret.getBytes("UTF-8"), Algorithm) );
Rfc2822Fmt.setTimeZone(TimeZone.getTimeZone("GMT"));
// Set up the request
URL url = new URL(host + uri);
ClientConfig config = new ClientConfig();
Client client = JerseyClientBuilder.newClient(config);
// Build the signing string and the Authorization header
String rfc2822 = Rfc2822Fmt.format( new Date() );
String sha256 = getSha256(payload);
int clen = payload.getBytes("UTF-8").length;
String ctype = MediaType.APPLICATION_JSON;
String signingStr = ("post"+url.getPath()+url.getHost()+rfc2822+sha256+clen+ctype).toLowerCase();
String signature = new String(Base64.getEncoder().encode(Hmac.doFinal(signingStr.getBytes("UTF-8"))), "UTF-8");
String authHeader = String.format(PostHeaderFmt, clientID, signature, sha256, clen, ctype);
// Add the headers declared by the authorization to the request
// Initiate the request
Response response = client
.target(host)
.path(uri)
.request(MediaType.APPLICATION_JSON_TYPE)
.header("Date", rfc2822)
.header("Authorization", authHeader)
.header("X-Content-Sha256", sha256)
.header("Content-Length", clen)
.header("Content-Type", ctype)
.post(Entity.entity(payload, MediaType.APPLICATION_JSON_TYPE));
if (response.getStatus() != 201 && response.getStatus() != 202 && response.getStatus() !=200 ) throw new IOException("Bad response: "+response.getStatus());
System.out.println(response.getStatus());
System.out.println(response.readEntity(String.class));
}
private static void getRequest(String host, String uri, String clientID, String clientSecret) throws Exception {
Hmac.init(new SecretKeySpec(clientSecret.getBytes("UTF-8"), Algorithm));
Rfc2822Fmt.setTimeZone(TimeZone.getTimeZone("GMT"));
// Set up the request
URL url = new URL(host + uri);
ClientConfig config = new ClientConfig();
Client client = JerseyClientBuilder.newClient(config);
// Build the signing string and the Authorization header
String rfc2822 = Rfc2822Fmt.format(new Date());
String signingStr = ("get" + url.getPath() + url.getHost() + rfc2822).toLowerCase();
// String signature = Base64.encodeBase64String(Hmac.doFinal(signingStr.getBytes("UTF-8")));
String signature = new String(Base64.getEncoder().encode(Hmac.doFinal(signingStr.getBytes("UTF-8"))), "UTF-8");
String authHeader = String.format(GetHeaderFmt, clientID, signature);
// Initiate the request
Response response = client
.target(host)
.path(uri)
.request(MediaType.APPLICATION_JSON_TYPE)
.header("Date", rfc2822)
.header("Authorization", authHeader)
.get();
if (response.getStatus() != 200) throw new IOException("Bad response: " + response.getStatus());
System.out.println(response.readEntity(String.class));
}
private static String getSha256(String text) throws NoSuchAlgorithmException,UnsupportedEncodingException {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(text.getBytes(StandardCharsets.UTF_8));
return new String(Base64.getEncoder().encode(hash), "UTF-8");
}
public static void main(String[] args) throws Exception {
boolean getExample = false;
if (getExample) {
String uri = "/audience-onramp/api/v1/audiences/3392037";
getRequest(Host, uri, ClientId, Secret);
} else {
String payload = "{\"name\":\"test_audience_123\"}";
String uri = "/audience-onramp/api/v1/audiences";
post(payload, Host, uri, ClientId, Secret);
}
}
}
OnRamp API programmer's reference
The following section detials the methods and response codes for the OnRamp API.
Methods
The following table details the methods and parameters supported by the OnRamp audiences, segments, and users APIs.
| API | HTTP Method | Endpoint | Description | GET Response/ POST Request Body |
|||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Audience
|
POST |
https://portal.datalogix.com/audience-onramp/api/v1/audiences |
Create an audience. |
OnRamp Audiences API - POST Request: JSON Body Parameters
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
| GET (List) |
https://portal.datalogix.com/audience-onramp/api/v1/audiences? |
Get a list of audience details and metrics. |
OnRamp Audience API - GET Request (List): URI Parameters
OnRamp Audience API - GET Request (Read): URI Parameters
OnRamp Audiences API - GET Response: JSON Body Parameters
|
||||||||||||||||||||||||||||||||||||||||||||||||||||
| GET (Read) | https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId} | Get details and metrics for a specific OnRamp audience: | |||||||||||||||||||||||||||||||||||||||||||||||||||||
| Segments | POST |
https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/segments |
Add segments to an audience. |
OnRamp Segments API - POST Request: JSON Body Parameters
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
| Users | POST | https://portal.datalogix.com/audience-onramp/api/v1/audiences/{audienceId}/users | Add users to segments. |
OnRamp Users API - POST Request: JSON Body Parameters
|
|||||||||||||||||||||||||||||||||||||||||||||||||||
HTTP response codes
Your OnRamp API requests will return the following JSON-formatted data that includes an HTTP status code and a message description:
| HTTP Status Code | Message Description | API |
|---|---|---|
| 201 | Audience created successfully. | Audiences POST
Segments POST |
|
202 |
Users added successfully. |
Users |
|
400 |
Invalid request. This most likely indicates that there is a missing parameter or malformed JSON in the body of the POST request. |
All |
| 401 | Unauthorized. This indicates that the OnRamp API call is missing a valid API key or valid method signature.
|
All |
| 404 | Not found. No audience with the provided audience ID exists. | Audiences GET (Read) |
|
500 |
Internal error. This indicates a service error with the OnRamp API. Contact your Oracle Data Cloud representative. |
All |