Sending API Requests

This topic explains how to send HTTP requests to the Oracle Audience Segmentation API.

Introduction

A basic request has several components not including authentication. An Oracle Audience Segmentation API request follows the form:

[Verb][AccountURL]/[Endpoint]

Where...

  • Verb represents the HTTP request "method" type. Oracle Audience Segmentation's API services support four different verbs or methods: POST, GET, PUT and DELETE. In terms of database functions, these HTTP verbs correspond to the basic operations of "CRUD": create, read, update and delete.
  • AccountURL is your URL to your Oracle Audience Segmentation account. Contact your tenant administrator if you do not know your Account URL.
  • Endpoint is the path of the Oracle Audience Segmentation resource.
  • Some endpoints also require an {AccessKey}, this is your tenant access key, see Determining Tenant Access Keys and Tenant IDs if you do not know yours.

Therefore an example of a complete request would be as follows:

GET https://oracle-tenant.audience.ocs.oc.com/api-metadata/v1/{AccessKey}/metadata/tables

Learn more by watching the video

Use cases

  • Leverage the API to create programs and scripts to automate tasks you would normally use the user interface to do, thus alleviating the need for manual work and thereby saving time.

  • Extend your use of the Oracle Audience Segmentation platform by adopting capabilities of the platform that are only available using the API endpoints.

Workflow

The sequence of steps required for processing Oracle Audience Segmentation REST API requests is:

  1. Client obtains an authentication token.

  2. Client sends a request to an Oracle Audience Segmentation API endpoint. For example:

    Authorization: Bearer <token>
Content-Type: application/json
GET https://oracle-tenant.audience.ocs.oc.com/api-metadata/v1/e2a7a0df2410470d85ef69c8dad2bdb8/metadata/tables
 

API Endpoints

The Oracle Audience Segmentation platform provides the following API endpoints.

API Description Service URI
Data Density

The data density figure represents the percentage of records that have values for an attribute. For example, if only half the total number of records in the Address data object have a non-null value populated for the State attribute, then the data density value for State is 50%.

Use the data density API for the following use cases:

  • Checking how many rows exist in a data object.
  • Checking per data object attribute, how many are null/populated.
  • Checking the density is per attribute, i.e. the percentage of records with the attribute populated.
 /api-data/v1/{access-key}/data/density/entities/{tableId}
Data Query

The Data query APIs are used to execute queries against data objects using MCPS query objects.

 /api-data/v1/{access-key}/data/query/
Jobs

Jobs are tasks to transfer data or to complete system tasks. You can manage and monitor jobs from the Jobs page.

The Jobs API enables you to create, update, and retrieve your jobs.

 /api-metadata/v1/{access-key}/metadata/jobs
Attribute Lookups

Oracle Audience Segmentation allows you to look up attribute values on the segmentation canvas so that you can select values from a list instead of manually entering them. Oracle Audience Segmentation comes with out-of-the-box lookups for many attributes.

The Attribute lookup API is used to create, retrieve, and update the lookups in your Oracle Audience Segmentation instance.

 /api-metadata/{access-key}/metadata/lookups
Destinations (Sink Instances)

Oracle Audience Segmentation allows you to export data and segments by running export jobs and campaign jobs. Before setting up an export job or campaign in Oracle Audience Segmentation, you will need to create the destination, which includes all the details of where the data will be exported to.

Note: To create the destination, you will need to provide your own Secure FTP site to enable the data transfer. Oracle Audience Segmentation does not provide Secure FTP sites.

You can use the Destinations API to create, update, and retrieve your Destinations.

 /api-metadata/v1/{access-key}/metadata/sinkinstances
Sources

You will need to create sources in Oracle Audience Segmentation so that customer data can be imported into the data model. These sources will provide all the details needed so that Oracle Audience Segmentation can run ingest jobs and import data.

Ensure source files are formatted correctly by reviewing CSV file standards for Oracle Audience Segmentation.

Note: To create the source, you will need to provide your own Secure FTP site to enable the data transfer. Oracle Audience Segmentation does not provide Secure FTP sites.

The sources API is used to programmatically manage the sources in your instance.

 /api-metadata/v1/{access-key}/metadata/sourceinstances
Stream

The Streaming API is used to ingest data directly from applications into Oracle Audience Segmentation. Unlike using in ingest job, when data is streamed you cannot map or transform the data. A typical use case could be to send data updates to Oracle Audience Segmentation once customers save their profile.

/api-stream/v1/<tenantAccessKey>/data/entities
Data Objects

Oracle Audience Segmentation comes with a default set of data objects for your data model that gives the tools necessary to effectively manage your customer data. However, if the existing data objects don't fully meet the needs of your organization, you can create custom data objects.

Use the Data Objects API to retrieve and update information about your data objects and their attributes.

 /api-metadata/v1/{access-key}/metadata/tables