Account-level API

About this API

To get descriptions for all endpoints that are associated with a particular UBX account, you must include an account-level authentication key as the authorization bearer for the API call. The authentication key must be an account level authentication key that is provided to you by IBM.

When you call GET /v1/endpoint with an account-level authentication key, UBX returns descriptions for all endpoints that are associated with the account.

To return information for only one endpoint that is registered to a UBX account, you can include the endpoint ID as a URL parameter in the call.

In the URL for the call, you can include additional optional URL parameters to request specific characteristics for each endpoint that is registered to the account. Separate parameters with &.

Request

Direct the API call to the base URL that is assigned to your UBX account.

The response lists the endpoint properties as they were entered during event registration with PUT v1/endpoint.

To specify the user account, provide the authentication key for the account as the authorization bearer in the API call.

Request format (as a curl command):

curl -v 
-X GET 
-H "Authorization: Bearer <account authentication key>" 
<base URL>/v1/endpoint?<parameter 1>&<parameter 2>&<parameter n>

Note: the Authorization: Bearer must be an account-level authentication key.  

For example, calling the following URL returns descriptions for up to 20 segments that provide audience data from the various endpoints that are registered with UBX on behalf of the UBX account that is associated with the account-authentication key.

<base
URL>/v1/endpoint?segment=true&source=true&loadSegments=true&startRecord=1&pageSize=20

Response

UBX public APIs return standard HTTP 1.1 response codes.

GET <base URL>/v1/endpoint provides responses as follows.

About this API

Call DELETE /v1/endpoint/{endpointId}remove an endpoint from UBX. Calling DELETE /v1/endpoint/{endpointId} provides the same request options and the same responses as DELETE /v1/endpoint. However, because you call DELETE /v1/endpoint/{endpointId} from the account level, you must specify the endpoint ID as a URL parameter.

Request

Direct the API call to the base URL that is assigned to your UBX account.

Example request (as a curl command):

Request:
curl -v 
  -X DELETE
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -H "Content-Type: application/json" 
  <base URL>/v1/endpoint/<endpointID>

Other than including the endpoint ID as a parameter in the API call, the details of the API request and the API response are the same as PUT /v1/endpoint. For more information about the PUT /v1/endpoint API, see DELETE /v1/endpoint.

About this API

Call PUT v1/endpoint/{endpointID} to register an IBM application, or approved IBM Business Partner application, as an endpoint in UBX on behalf of a registered UBX user. Calling PUT /v1/endpoint/{endpointId} API provides the same request options
and the same responses as PUT /v1/endpoint. However, because you call PUT v1/endpoint/{endpointID} from the account level, you must specify an endpoint ID as a URL parameter.

Request

Direct the API call to the base URL that is assigned to your UBX account.

Example request, in this example to register as an event endpoint, (as a curl command):

 
Event publisher and subscriber endpoints (curl)
curl -v 
  -X PUT 
  -H "Authorization: Bearer <1234-abcd-5678-efgh>" 
  -H "Content-Type: application/json" 
  -d '{“providerName” : “<name of provider>”,“name” : “<name of endpoint>”,
     “description” : “<description>”, "endpointTypes" : { "event" : 
     {"<source | destination>" : {  "enabled" : true,  
     "destinationType" : "<push | pull>" }  } }, 
     “url” : “<URL for endpoint>”}' 
     <base URL>/v1/endpoint/<endpoint ID>

Other than including the endpoint ID as a parameter in the API call, the details of the API request and the API response are the same as PUT /v1/endpoint. For more information about the PUT /v1/endpoint API, see PUT /v1/endpoint.

About this API

There are some provisioning or integration use cases in which a database name or ID must be modified after endpoint registration. UBX provides the PUT /v1/endpoint/database API if such a use case becomes necessary for your application.

Request

Direct the API call to the base URL that is assigned to your UBX account.

You can use either an endpoint level or an application level authentication key as the authorization bearer for the call. If you use an application level authentication key, you must include the endpoint ID in the call as a means to identify the endpoint. If you use an endpoint level authentication key, the key is used to identify the endpoint.

Request format (as a curl command):

curl -X PUT 
  <base URL>/v1/endpoint/database 
  -H 'accept-charset: UTF-8' 
  -H 'authorization: Bearer <endpoint or application authentication key>' 
  -H 'cache-control: no-cache' 
  -H 'content-type: application/json' 
  -H 'postman-token: <token>' 
  -d {
      "endpointId": <endpoint ID>,
      "databaseId": "<database ID>",
      "marketingDatabaseName": "<database name>"
}

Response

UBX public APIs return standard HTTP 1.1 response codes.

PUT <base URL>/v1/endpoint/database provides responses as follows.

Before you begin

Register one or more endpoints by calling PUT v1/endpoint or PUT /v1/endpoint/{endpointId}.

About this API

To disable one of multiple endpoints that are registered to an account, you must include an account-level authentication key as the authorization bearer for the API call. The authentication key must be an account-level authentication key that is provided to you by IBM.

Request

Direct the API call to the base URL that is assigned to your UBX account.

Add the endpoint ID of the endpoint that you want to disable as a parameter to the URL, as shown in the example.

Request format (as a CURL command)

curl -v 
    -X PUT
    -H "Authorization: Bearer <endpoint authentication key>" 
    -H "Content-Type: application/json" 
    <base URL>/v1/endpoint/disable/<endpoint ID>

Response

UBX public APIs return standard HTTP 1.1 response codes.

PUT v1/endpoint/disable/{endpoint ID} provides responses as follows.

Before you begin

Register one or more endpoints by calling PUT v1/endpoint or PUT /v1/endpoint/{endpointId}.

About this API

To enable one of multiple endpoints that are registered to an account, you must include an account-level authentication key as the authorization bearer for the API call. The authentication key must be an account-level authentication key that is provided to you by IBM.

Request

Direct the API call to the base URL that is assigned to your UBX account.

Add the endpoint ID of the endpoint that you want to enable as a parameter to the URL, as shown in the example.

Request format (as a CURL command)

curl -v 
    -X PUT
    -H "Authorization: Bearer <endpoint authentication key>" 
    -H "Content-Type: application/json" 
    <base URL>/v1/endpoint/enable/<endpoint ID>

Response

UBX public APIs return standard HTTP 1.1 response codes.

PUT <base URL>/v1/endpoint/enable/{endpoint ID} provides responses as follows.

About this API

Call this API to get a description for a specific audience that is provided or received by an endpoint that is registered with UBX on behalf of a UBX user account. The call requires a valid authentication key, which is specific to the user account and endpoint.

You must provide the following information to call this API:

• Authentication key that is associated with a UBX user account
• Endpoint ID for the endpoint in which the audience is defined
• Segment ID for the segment that you want to describe

You must also have user authorization to access the endpoint.

Request

Direct the API call to the base URL that is assigned to your UBX account.

Example request (as a curl command):

curl -v 
    -X GET 
    -H "Authorization: Bearer 1234-abcd-5678-efgh" 
    <base URL>/v1/endpoint/<endpointID>/segments/{<segmentID>}

Response

{
  "segment_attributes":
  [  
    {"name":"<attribute name>","type":<attribute type>}, 
  ],
  "id":<segment ID>,  B:Segment identification
  "name":"<segment name>",
  "description":<brief description>
}  

"id":45311,
  "idString":null,
  "name":"100Cust",
  "description":null
}

EXAMPLE:
{
  "segment_attributes":
  [  
    {"name":"LIST_ID","type":null},
    {"name":"MAILING_ID","type":null},
    {"name":"RECIPIENT_ID","type":null},
    {"name":"EMAIL","type":null},
    {"name":"CRM Lead Source","type":null},
    {"name":"cookieId","type":"0"},
    {"name":"sessionId","type":"0"},
    {"name":"Email","type":null}
  ],

A: Attributes

B: Segment identification

About this API

The response that this API provides depends on the producer type of the audience source endpoint.

• If the source endpoint is a PULL audience provider and the destination endpoint is a PUSH audience consumer: UBX automatically performs the entire process of uploading audience data from the source endpoint, joining audience identifiers if possible, and downloading the audience data to the destination endpoint.
• If the source endpoint is a PUSH audience provider: UBX creates the export job but waits for the source endpoint to upload audience data. UBX puts the job in WAITING_TO_RECIEVE_DATA status. To continue the audience sharing process, the source endpoint must call POST /v1/jobs/{jobId}/data to upload the audience data to UBX.
• If the source endpoint is a PULL audience consumer: UBX creates the export job but waits until the consumer audience data is ready to download. When consumer audience data is ready to download, the status of the job changes to READY_FOR_DOWNLOAD. To download the audience data, call GET /v1/jobs/{jobId}/segmentDataFiles/{fileName}.

Calling POST /v1/jobs/segmentExport from a segment producer endpoint to create a waiting segment export job makes it possible for UBX users to use the UBX user interface to upload audience data from the segment producer endpoint to UBX on demand.

Request

Direct the API call to the base URL that is assigned to your UBX account.

You must use an account-level authorization key as the authorization bearer for this API call.

Example request (as a curl command):

curl -v 
  -X PUT
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -d '{
        "endpointID":<source endpointID>,
        "segmentID":<source segmentID>|"segmentIDString":<string segment ID (source)>,
        "segmentName":"<name of the segment>",
        "destinationEndpointID":<destination endpointID>,
        "destinationSegmentName":"<destination segment name>",
        "exportCategory":"<category>",
        "action": "<action type>",
        "sourceIdentifiers":["<soure identifiers>"],
        "destinationIdentifier":"<destination identifier>",
        "attributeMappings":{"<source attribute>":"<destination attribute>"},
        "updateIdentities":true|false
        "minCount":"<integer>",
        "scheduleDetails": {schedule}
       }'
     <base URL>/v1/jobs/segmentExport

The following table describes the JSON payload of the call.

{
  "endpointID":<endpoint ID (source)>,
  "segmentID":<segment ID (source)>|"segmentIDString":<string segment ID (source)>,
  "segmentName":<name of the segment>,

  "destinationEndpointID":<endpointID (destination)>,
  "destinationSegmentName":"<segment name (destination)>",
  "destinationSegmentDescription":"<segment description (source)>",
  "destinationSegmentID":"<destination Segment ID>",
  "exportCategory":"<category>",

"action": "<action type>",

"sourceIdentifiers":["<source identifier>,<source identifier>]",
    "destinationIdentifier":"<destination identifier>",
    "attributeMappings":{"<attribute (source)>":"<attribute (destination)>"},

"updateIdentities":true|false

"minCount":<inetger>,

"scheduleDetails":{
        "runNow":true|false,
        "runRepeat":true|false,
        "daysOfWeek":<day of the week>,
        "daysOfMonth":<day of the month>,
        "monthsOfYear":<months of the year>,
        "year":<the year>,
        "startHour":"<the hour to start>",
        "startMinute":"<the minute to start>",
        "startSecond":"<the second to start>",
        "startDate":"<the start date>",
        "endDate":<the end date>,
        "timeSliceStartDate":<date>,
        "timeSliceEndDate":<date>
    },

A: Identify the source segment

B: Identify the destination segment

C: Specify the action of the call

D: Specify identity and attribute mapping

E: Indicate whether the UBX Identity Store is to be updated

F: Set minimum number of records

G: Schedule audience sharing

Response

UBX public APIs return standard HTTP 1.1 response codes.

POST /v1/jobs/segmentExport provides responses as follows.

What to do next

If the source endpoint is a PUSH audience provider, you can call POST /v1/jobs/{jobId}/data to upload a segment to the export job that UBX holds in WAITING_TO_RECIEVE_DATA state.

If the destination endpoint is a PULL audience consumer, you can call GET /v1/jobs/{jobId}/segmentDataFiles/{fileName} to download audience data.

Specify the job ID that POST /v1/jobs/segmentExport returns.

About this API

In most cases, UBX gathers identity data by examining events that are produced and consumed by endpoints. As such, it can take new UBX endpoints that use this process some time to build a large repository of identity data within the UBX Identity Store. However, if your endpoint already has a repository of identity data, you can upload that data in bulk to the UBX Identity Store by using the POST /v1/jobs/identityImport API.

The response that this API provides depends on the producer type of the source endpoint.

• If the source endpoint is a PULL segment producer, the API call initiates the identity data upload and returns a generated job ID. Additionally, it schedules a new job to check the endpoint’s export data job status. As a result, UBX periodically checks the jobs status until it reads as complete and the identity data is uploaded.
• If the source endpoint is a PUSH audience provider: UBX creates the export job but waits for the source endpoint to upload audience data. UBX puts the job in WAITING_TO_RECIEVE_DATA status. To continue the audience sharing process, the source endpoint must call POST /v1/jobs/{jobId}/data to upload the audience data to UBX.

Request

You must use an account-level authentication key as the authorization bearer in the API call.

Direct the API call to the base URL that is assigned to your UBX account.

Example request (as a curl command):

curl -v 
  -X PUT
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -d '{
        "endpointID":<source endpoint ID>,
        "segmentID":<source segment ID>|"segmentIDString":<string segment ID (source)>,
        "databaseID":<source database ID>
        "sourceIdentifiers":["<identifier name>, <identifier name>"]
        "scheduleDetails":{
        "runNow":true|false,
        "runRepeat":true|false,
        "daysOfWeek":<day of the week>,
        "daysOfMonth":<day of the month>,
        "monthsOfYear":<months of the year>,
        "year":<the year>,
        "startHour":"<the hour to start>",
        "startMinute":"<the minute to start>",
        "startSecond":"<the second to start>",
        "startDate":"<the start date>",
        "endDate":<the end date>,
        "timeSliceStartDate":<date>,
        "timeSliceEndDate":<date>},
       }'
     <base URL>/v1/jobs/identityImport

The following table describes the JSON payload of the call.

{
  "endpointID":<endpoint ID (source)>,
  "segmentID":<segment ID (source)>|"segmentIDString":<string segment ID (source)>,
  "databaseID":<source database ID>

"sourceIdentifiers":["<identifier name>, <identifier name>"]

"scheduleDetails":{
        "runNow":true|false,
        "runRepeat":true|false,
        "daysOfWeek":<day of the week>,
        "daysOfMonth":<day of the month>,
        "monthsOfYear":<months of the year>,
        "year":<the year>,
        "startHour":"<the hour to start>",
        "startMinute":"<the minute to start>",
        "startSecond":"<the second to start>",
        "startDate":"<the start date>",
        "endDate":<the end date>,
        "timeSliceStartDate":<date>,
        "timeSliceEndDate":<date>
    },

A: Identify the source segment

B: Specify identity and attribute mapping

C: Schedule the identity data upload

Response

UBX public APIs return standard HTTP 1.1 response codes.

POST /v1/jobs/identityImport provides responses as follows.