Application API: Define applications

APIs to create and maintain UBX applications. UBX applications contain features that make it possible to register multiple endpoints that share a common set of properties and characteristics.

POST /v1/application

Create and define a UBX application.

About this API:

In UBX, an application is a collection of metadata that describes an application or business solution that UBX users can select as an endpoint. As an endpoint provider, you define the application once and reference the application definition when you create new endpoint registrations in response to UBX user requests.

Request:

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

When you call v1/application, you can omit JSON elements that do not apply to the type of application that you are creating. For example, when you create an application that provides audience data (a segment source), you can omit endpoint type properties for segment destination, event source, and event destination endpoint types.

The following example illustrates a request (using curl) to create an application that publishes events:

curl -v 
-X POST 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
-d ’{“providerName” : “<name of provider>”,"description" : "<endpoint description>",
“displayName” : “<name of endpoint>”,“hashAlgorithm” : “<default hashing method>”, 
"endpointTypes" : { "event" :{"source" : { "enabled" : true,"dataWindow" : <days>,
"sourceType" : "push" } } },
https://<base URL>/v1/application

The following table describes the complete JSON payload for the call.

Request JSON
{
  "providerName": "<endpoint provider name>",
  "description": "<endpoint description>",
  "displayName": "<endpoint name>",
  "hashAlgorithm": <algorithm type>,
  "endpointTypes": {
      "event": {
         "source": {
            "enabled": <true|false>,
            "dataWindow": <days>,
            "sourceType": "<push|pull>"
            },
         "destination": {
            "enabled": <true|false>,
            "destinationType": "<push|pull>"
            }
         }  
      "segment": {
         "source": {
            "enabled": <true|false>,
            "dataWindow": <days>,
            "sourceType": "<push|pull>"
            },
         "destination": {
            "enabled": <true|false>,
            "destinationType": "<push|pull>"
            "shareActions" : {                    
                "add": <true|false>,
                "remove": <true|false>,
                "replace": <true|false>
                "defaultShareAction":  <"ADD"|"REMOVE"|"REPLACE">
               }
            }
         },
      },
  "marketingDatabasesDefinition": {
      "marketingDatabases": [
         {
         "id": <string>,
         "name": "<source database name>",
         "identifiers": [
            {
            "name": "<identifier name>",
            "type": "<identifier type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>,
            "isCaseSensitive": <true|false>, 
            "isEventOnly": <true|false>
            }
            ],
         "attributes": [
            {
            "name": "<attribute name>",
            "type": "<attribute type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>,
            "isCaseSensitive": <true|false>
            },
         ]
      }
      ]
  }
}

Identify and describe the application

In the application definition, specify information that UBX requires to display and describe the business solution as a UBX endpoint in the UBX user interface. As required, you can specify a hashing algorithm to obscure potentially sensitive identity and attribute data.

Properties to describe the endpoint that is based on the UBX application (excerpt from JSON)
 "providerName": "<endpoint provider name>",
  "description": "<endpoint description>",
  "displayName": "<endpoint name>",
  "hashAlgorithm": <algorithm type>,
Property Use Data type Valid value Description
providerName Required String As defined by the business solution. Name of the endpoint provider, typically your business name, as you want it to appear in the UBX user interface. Must be the provider name that you submitted to IBM when it provisioned your UBX account.
description Optional String As defined by the business solution. Description of the endpoint, as you want it to appear in the UBX user interface.
displayName Required String As defined by the business solution. Name of the endpoint, as you want it to appear in the UBX user interface. For example, a product name.
hashAlgorithm Optional String

MD5

SHA1

SHA256

EMAIL_SHA256

PHONE_SHA256

The hashing algorithm that UBX uses when destination endpoints require that UBX hash identity and attribute data.

The algorithm that you specify here is a global definition that applies to all types of endpoints that you base on the application.

Enable event publishers and subscribers

In the application definition, you must specify if endpoints that are based on this application are an event source (publisher) or an event estination (subscriber). Use the event properties to enable endpoints that are based on the application.

Event properties (excerpt from JSON)
 "event": {
         "source": {
            "enabled": <true|false>,
            "dataWindow": <days>,
            "sourceType": "<push|pull>"
            },
         "destination": {
            "enabled": <true|false>,
            "destinationType": "<push|pull>"
            }
         }  
Property Use Data type Valid value Description
source Required for event publishers Not applicable Not applicable Enter values for source properties if the endpoint is an event publisher.
destination Required for event subscribers Not applicable Not applicable Enter values for destination properties if the endpoint is an event subscriber.
enabled Required Boolean true | false

Enable either source or destination.

dataWindow Optional Integer Number of days Typically used only when selecting and exchanging audience data.
sourceType Required for event publishers String

push

pull

Push: allows the endpoint to push data to UBX.

Pull: the endpoint prepares and stores event data for download and waits for UBX to retrieve the data.

destinationType Required for event subscribers String

push

pull

Push: allows UBX to push event data to the endpoint.

Pull: UBX prepares and stores event data for download and waits for the endpoint to retrieve the data.

Enable audience sources and destinations

In the application definition, you must specify if endpoints that are based on this application are audience sources (publishers) or an audience destinations (subscribers). Use the segment properties to enable endpoints that are based on the application.

Audience properties (excerpt from JSON)
     
      "segment": {
         "source": {
            "enabled": <true|false>,
            "dataWindow": <days>,
            "sourceType": "<push|pull>"
            },
         "destination": {
            "enabled": <true|false>,
            "destinationType": "<push|pull>" 
            "shareActions" : {                    
                "add": <true|false>,
                "remove": <true|false>,
                "replace": <true|false>
                "defaultShareAction":  <"ADD"|"REMOVE"|"REPLACE">
               }
            }
         },
Property Use Data type Valid value Description
source Required for audience publishers Not applicable Not applicable Enter values for source properties if the endpoint is an audience source.
destination Required for audience consumers Not applicable Not applicable Enter values for destination properties if the endpoint is an audience destination.
enabled Required Boolean true | false

Enable either source or destination.

dataWindow Optional Integer Number of days UBX users can specify a date range to limit how much data to upload to UBX. To restrict users to a specific number of days, specify the number of days that can be included in the date range, relative to the date that the export runs.
sourceType Required for audience providers String

push

pull

Push: allows the endpoint to push data to UBX.

Pull: the endpoint prepares and stores data for download and waits for UBX to retrieve the data.

destinationType Required for audience subscribers String

push

pull

Push: allows UBX to push event data to the endpoint.

Pull: UBX prepares and stores data for download and waits for the endpoint to retrieve the data.

shareActions Required for audience subscribers Not applicable Not applicable Options that define how audience providers are allowed to modify the destination database with new audience records.
add Required Not applicable true | false Audience source is allowed to add records to the destination database.
remove Optional Not applicable true | false Audience source is allowed to remove selected records from the destination database.
replace Optional Not applicable true | false Audience source is allowed to remove records from the destination database and replace them with new records.
defaultShare Action Required ADD|REMOVE| REPLACE

Specify the default method for modifying the destination database.

UBX allows ADD by default.

Source database for attributes and identifiers

Use properties in the marketing Databases Definition section to describe identifiers and attributes in event or audience data, including the source and schema of the source for identity lookup data.

You can use the marketing databases properties to describe the source and schema of the source for identity lookup data for events and audiences. Including these properties to identify the source database is optional. However, if you choose to identify the audience source, you must
indicate the database name.

Marketing database properties (excerpt from JSON)
  "marketingDatabasesDefinition": {
      "marketingDatabases": [
         {
         "id": <string>,
         "name": "<source database name>",
         
         //"identifiers" and "attributes" sections are removed in this example
      }
      ]
  }
Property Use Data type Valid value Description
id Optional String As defined in your business systems Identifier for the source database, as applicable.
name Required if you identify the audience database. String As defined in your business systems Name of the database that provides the audience data.

Audience identifiers and attributes

Use the marketing Databases Definition properties to describe identifiers and
attributes in event or audience data, including the source and schema of the source for identity
lookup data. Specifying a database name is optional.

UBX uses identifier attributes to identify specific individuals in an audience. Over time, UBX merges identity records of the same type for the same individual to provide a detailed view of the customer in multiple contexts. You can define one or more attributes that relate to a specific individual.

You must specify the name of the identifier and type of data that the identifier provides. To support augmenting audience identities, the type of identifier in the audience source must match the type of identifier in the destination. The names might be different, but the types must be same.

You can define or more attributes that describe at least some of the individuals that are present in an audience.

Audience identifiers and attributes (excerpt from JSON)
         "identifiers": [
            {
            "name": "<identifier name>",
            "type": "<identifier type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <hash algorithm type>,
            "isRequired": <true|false>,
            "isCaseSensitive": <true|false>,
            "isEventOnly": <true|false>
            }
            ],
         "attributes": [
            {
            "name": "<attribute name>",
            "type": "<attribute type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>,
            "isCaseSensitive": <true|false>
            }
         ]
Property Use Data type Valid value Description
name Required String As defined in your business systems Name of the identifier or attribute as provided by the source endpoint.
type Required Identity type As defined in your business systems

Indicate the type of identifier. If possible, match the type to a UBX identity key.

The type that is specified in the audience source must match the type that is specified in the audience destination.

hashMode Optional String

NONE

HASHED

REQUIRED

If the endpoint requires obscuring identifiers or attributes, specify how to hash the values, as follows.

None: No hashing is required. (Can be null.)

Hashed: The audience provider hashes the value, by using the algorithm that is specified in the hashAlgorithm property.

Required: UBX must hash the value that is sent to the audience destination. If the destination endpoint does not specify an algorithm, use the default algorithm.

hashAlgorithm Optional String

MD5

SHA1

SHA256

EMAIL_SHA256

PHONE_SHA256

If the hashMode is REQURED, then this property specifies the algorithm that the audience source endpoint uses to hash the identifier or attribute.
isRequired Required Boolean

true | false

Indicates whether the source endpoint must specify the identifier or attribute.
isCaseSensitive Optional Boolean

true | false

Instructs UBX to convert upper case or mixed case identifier values to lower case so that UBX can join the identifiers. UBX matches lower case values only. By default, this field is null, which UBX treats as true (case-sensitive).

If false, UBX converts the identifier values to lower case and joins identifiers with matching values.

UBX evaluates and converts values for identifiers. It does not evaluate values for attributes.

isEventOnly Optional Boolean

true|false

Indicates whether the identifier applies only to event data. By default, this property is false, which means the identifier can appear in event and audience data. If true, the identifier cannot be used to identify audience members. Can be null.

Note: Do not apply to attributes. For identifiers only.

Response:

UBX public APIs return standard HTTP 1.1 response codes.

For a successful call, the response includes a JSON payload that matches the payload of the request but also includes a new, system-generated property: "id" : "{application id}.

For example, the returned JSON includes the new application ID, as illustrated here.

Returned JSON (partial)
 
  "id":<applicationID>,
  "providerName": "<endpoint provider name>",
  "description": "<endpoint description>",
  "displayName": "<endpoint name>",
  "hashAlgorithm": <algorithm type>,

  //Remainder of the returned JSON payload is not shown in this example.

 

UBX uses the value of this new property to identify the application that the API call creates.

Record the value for "id" because you must specify it in other application API calls.

PUT /v1/application/{applicationid}

Update the definition of a UBX application.

About this API

Call PUT <base URL>/v1/application/{application Id} to make changes to the definition of a UBX application. For example, as you are implementing your business solution with UBX, you can call this API to make adjustments.

Request

You must specify the account-level authentication key that IBM provided for your UBX account.

The application ID is the value that UBX generated when you created the application with the call to POST v1/application.

The structure of the JSON payload for the PUT call is identical to the payload structure for the POST call. Update the values that you want to change.

The following example illustrates a request (using curl) to update an application that publishes events:

curl -v 
-X PUT 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
-d ’{"id":<applicationID>,“providerName” : “<name of provider>”,
"description" : "<endpoint description>",“displayName” : “<name of endpoint>”,
“hashAlgorithm” : “<NEW hashing method>”,"endpointTypes" : 
{ "event" :{"source" : { "enabled" : true,"sourceType" : "push" } } },
https://<base URL>/v1/application/<applicationID>

Response

UBX public APIs return standard HTTP 1.1 response codes.

A successful call response includes a JSON payload that contains the updated values. The value for applicationID does not change.

GET /v1/application

Request details for all applications that are associated with a specific account-level authentication key.

About this API

This API returns details for all applications that are associated with the account authentication key that was specified when the application was created with a call to POST v1/application. The response includes application details as JSON for each application, including the application ID for each application.

For example, you might call GET v1/application if you forget the application ID for an application.

Request

You must specify the account authentication key that you received from IBM for your UBX account as the authorization bearer.

The base URL is the URL that IBM assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to retrieve details for applications that were created with the specified authentication key:

curl -v 
-X GET 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application

Response

UBX public APIs return standard HTTP 1.1 response codes.

A successful response includes JSON payloads for each UBX application that was created with the account authentication key that you specified as the authorization bearer in the GET call.

The returned JSON matches the payload that was used to create each application with a call to POST v1/application.

GET /v1/application/{applicationid}

Retrieve information about an existing UBX application.

About this API

Call this API to get details for a specific UBX application.

Request

You must specify the application ID that UBX generates when you called POST v1/application to create the application. You must also specify the account authentication key that you received from IBM for your UBX account.

The base URL is the URL that IBM assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to retrieve details for applications that were created with the specified authentication key:

curl -v 
-X GET 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>

Response

UBX public APIs return standard HTTP 1.1 response codes.

A successful response includes a JSON payload that describes the specified application. The JSON matches the payload that was used in the POST v1/application call to create the application.

PUT /v1/application/{applicationid}/{status}

Update the visibility status of a UBX application.

About this API

Use this API to change the status of a UBX application. The status of a UBX application can be either PUBLIC or PRIVATE.

  • PUBLIC: the application is visible to all accounts in the UBX pilot environment.
  • PRIVATE: the application is visible only to authorized users in the UBX account in which the application was created.

Request

You must specify the account-level authentication key that IBM provided for your UBX account.

The application ID is the value that UBX generated when you created the application with the call to POST v1/application.

The base URL is the URL that IBM assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to change the visibility status of a specified UBX application:

curl -v 
-X PUT 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>/{status}

Response

UBX public APIs return standard HTTP 1.1 response codes.

For a successful call, the response returns a success code and the new status. For example, to restrict the visibility an application that is currently visible to all users in the UBX Pilot environment, a successful call to PUT v1/application/<applicationID/{status} returns:

200 OK, "PRIVATE"

GET /v1/application/{applicationid}/{status}

Determine the visibility status of a UBX application.

About this API

Use this API to determine the status of a UBX application.

The status of a UBX application can be either PUBLIC or
PRIVATE.

  • PUBLIC: the application is visible to all accounts in the UBX pilot environment.
  • PRIVATE: the application is visible only to authorized users in the UBX account in which the application was created.

Request

You must specify the account-level authentication key that IBM provided for your UBX account.

The application ID is the value that UBX generated when you created the application with the call to POST v1/application.

The base URL is the URL that IBM assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to change the visibility status of a specified UBX application:

curl -v 
-X GET 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>/{status}

Response

UBX public APIs return standard HTTP 1.1 response codes.

For a successful call, the response returns a success code and the new status. For example, to determine who can see the specified application, a successful call to PUT v1/application/<applicationID/{status} might indicate that it is currently visible to all users in the UBX Pilot environment, as follows:

200 OK, "PUBLIC"

DELETE /v1/application/{applicationid}

To delete a UBX application.

About this API

Use this API to remove the specified UBX application.

Request

You must specify the account-level authentication key that IBM provided for your UBX account.

The application ID is the value that UBX generated when you created the application with the call to POST v1/application.

The base URL is the URL that IBM assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to remove the specified UBX application:

curl -v 
-X DELETE 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>

Response

UBX public APIs return standard HTTP 1.1 response codes.

The call returns a 400 error if UBX detects an endpoint that references the application ID.

Join The Discussion

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