IBM Universal Behavior Exchange provides a collection of public REST APIs that endpoints
call to connect to UBX as producers and consumers of event and audience data.

The APIs include various properties to provide customer identifiers and event attributes as part
of the API call.

UBX endpoints call the UBX public APIs over SSL.

Calls to UBX public APIs must contain a valid authentication key that IBM provides to UBX users
for each endpoint that they register. The authentication key identifies the UBX endpoint and a
specific UBX user account that is associated with the endpoint.

All data exchanges through UBX occur on behalf of a specific UBX user and user account. Including
an authentication key with each API call ensures that the data is directed to the correct
destination and that customer identifiers are attributed to the correct UBX account. UBX does not
share identifier data across UBX accounts.

The authentication key must appear in the HTTP header of the API call. UBX rejects any API call
that does not specify an authentication key that UBX can associate with a valid UBX account.

For a complete description of the UBX public APIs, see UBX public API reference.


Audience producer: PULL

Endpoints that allow UBX to pull audience data from the endpoint are considered a
pull-type audience producer. To initiate the data exchange and related tasks, UBX calls APIs that
are implemented by the endpoint.

Often, cloud-based business applications (also referred to as SaaS applications)
connect to UBX as a pull-type audience producer.

The following table identifies the APIs that nay endpoint provider must implement to support
actions that are expected of a pull-type audience producer.

Action by the endpoint UBX API calls

Provide a list of audiences (segments) that are available to provide audience data.

GET v1/segments
Provide details about a specific source audience. GET v1/segments/
{segmentId}
Upload available data to UBX. If no data is available, UBX requests that you create a data
upload job.
GET v1/segments/
{segmentId}/data
Create a job to upload audience data when it becomes available. POST v1/jobs
Provide job status. UBX polls for job status. It continues to poll when data upload begins
and until the upload completes.
GET v1/jobs/{jobId}
Upload the requested audience data. GET
v1/jobs/{jobId}/data/ {jobDataId}

Audience producer: PUSH

Endpoints that upload audience data and metadata to UBX are considered to be a push-type
audience producer. To initiate the data upload and related tasks, the endpoint calls APIs that are
hosted by UBX.

For example, to avoid potential security concerns, business applications that are physically
installed in a local computer network as an On Premise application typically connect to
UBX as a push-type endpoint.

The following table identifies the APIs that the endpoint must call to support actions that are
expected of a push-type audience producer.

Action UBX API calls
Add a list to UBX that identifies segments that are ready for export to UBX. POST /v1/endpoint/{endpointId}/segments
Replace a list on UBX that identifies segments that are ready for export to UBX. PUT /v1/endpoint/{endpointId}/segments
Clear the list on UBX that identifies segments that are ready for export to UBX. DELETE /v1/endpoint/{endpointId}/segments
Remove a specific segment from the list on UBX that identifies segments that are ready for
export to UBX.
DELETE /v1/endpoint{endpointId}/segments/{segmentId}
Upload audience data and metadata to UBX in CSV format. POST /v1/jobs/{jobId}/data
Get a list of one or more jobs, identified by category, endpoint ID, or status. GET /v1/jobs/{jobCategory}
Get a specific job, identified by job category and job ID. GET /v1/jobs/{jobCategory}/{jobId}

Audience producer: PULL

Endpoints that allow UBX to pull audience data from the endpoint are considered a
pull-type audience producer. To initiate the data exchange and related tasks, UBX calls APIs that
are implemented by the endpoint.

Often, cloud-based business applications (also referred to as SaaS applications)
connect to UBX as a pull-type audience producer.

The following table identifies the APIs that nay endpoint provider must implement to support
actions that are expected of a pull-type audience producer.

Action by the endpoint UBX API calls

Provide a list of audiences (segments) that are available to provide audience data.

GET v1/segments
Provide details about a specific source audience. GET v1/segments/
{segmentId}
Upload available data to UBX. If no data is available, UBX requests that you create a data
upload job.
GET v1/segments/
{segmentId}/data
Create a job to upload audience data when it becomes available. POST v1/jobs
Provide job status. UBX polls for job status. It continues to poll when data upload begins
and until the upload completes.
GET v1/jobs/{jobId}
Upload the requested audience data. GET
v1/jobs/{jobId}/data/ {jobDataId}

Audience consumer: PUSH

Endpoints that allow UBX to push audience data to the endpoint are considered a push-type
audience consumer. To initiate the data exchange and related tasks, UBX calls APIs that are
implemented by the endpoint.

A push-type audience consumer is responsible for providing the means for UBX access and push the
audience data and related metadata to the endpoint.

Often, cloud-based business applications (also called SaaS applications) connect to
UBX as a push-type audience consumer.

The following table identifies the APIs that the consumer endpoint must implement to support
actions that are expected of a push-type audience consumer.

Action by the endpoint UBX API calls

Provide a list of audiences that are already available as a destination audience and that can
receive additional audience data or that can be modified by replacing or adding to existing
data.

GET v1/segments
Provide details about a specific destination audience. GET v1/segments/
{segmentId}
Create an audience on the destination endpoint. POST v1/segments
Add audience data to the specified destination audience, either as a new audience or to
existing audience.
POST v1/segments/
{segmentId}/data?ids={ID}
Replace all existing data in the specified destination audience with new audience
data.
PUT v1/segments/
{segmentId}/data?ids={ID}
Delete specific records in the specified destination audience. DELETE
v1/segments/{segmentId}/data?ids={ID}

Audience consumer: PULL

Endpoints that download audience data and metadata from UBX are considered to be a
pull-type audience producer. To initiate the data download and related tasks, the endpoint calls
APIs that are hosted by UBX.

Business applications that are physically installed in a local computer network as an On
Premise
application typically connect to UBX as a pull-type endpoint.

The following table identifies the APIs that the endpoint must call to support actions that are
expected of a pull-type audience consumer.

Action UBX API calls
Add a list to UBX that identifies segments that are ready for import to UBX. POST /v1/endpoint/{endpointId}/segments
Replace a list on UBX that identifies segments that are ready for import to UBX. PUT /v1/endpoint/{endpointId}/segments
Clear the list on UBX that identifies segments that are ready for import to UBX. DELETE /v1/endpoint/{endpointId}/segments
Remove a specific segment from the list on UBX that identifies segments that are ready for
import to UBX.
DELETE /v1/endpoint{endpointId}/segments/{segmentId}
Pull audience data files from UBX to a destination endpoint. GET /v1/jobs/{jobId}/segmentDataFiles/{fileName}
Clean up audience data files from UBX after downloading the data. DELETE/v1/jobs/{jobId}/segmentDataFiles/{fileName}
Mark an audience download job as complete and clean up files. PUT /v1/jobs/{jobid}/status/complete

Connection to UBX with account level access

To manage endpoints across an entire UBX user account, UBX provides APIs that can be
called at the account level. The account level APIs require account level access credentials from
IBM.

Action UBX API calls
Register specified endpoint with UBX. Requires account level authorization. PUT /v1/endpoint/{endpointId}
Delete a specific UBX endpoint. DELETE /v1/endpoint/{endpointId}
Get the details of a specified segment within a specified endpoint. GET /v1/endpoint/{endpointId}/segments/{segmentId}
Get a list of registered endpoints for an account, selected by various
characteristics.
GET /v1/endpoint
Start a job to export a specified segment from a specified source endpoint to a specified
destination endpoint.
POST /v1/jobs/segmentExport

Join The Discussion

Your email address will not be published. Required fields are marked *