Event API

Use UBX event API to register and publish events. UBX also provides API to monitor how
UBX customers subscribe to events that you publish through UBX.

POST /v1/event

Use the v1/event API to publish events from an event publisher endpoint to UBX. The structure of the JSON payload varies, depending on whether you publish events individually or in a batch.

Before you begin

The identifiers that you specify in calls to v1/event must be registered with UBX for use by your UBX account. To register an identifier, call POST v1 application or PUT v1/endpoint (for custom endpoints).

The event types that you specify in calls to v1/event must be registered with UBX for use by your UBX account. The event attributes that you specify must also be registered with UBX. To register event types and attributes that you support, call POST v1/eventtype.

Use only event codes defined by IBM. See Event types for a list of recognized event codes and event attributes.

About this API

You can publish events individually or in batches. UBX supports the following forms of event publication.

  • Individual events
  • Simple batch
  • Compound batch

Each method requires that you structure the JSON payload of the request differently.

vents

Note: UBX originally introduced event publication as individual events as the only way to publish events. The updated v1/event API is fully compatible with existing implementations for sending individual events.

Request

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

The v1/event API supports several properties to describe events, where and when the events occurred, and who initiated the event. How you publish events determines how you represent the properties in the request payload.

The following example (as a curl command) illustrates a request to publish an individual event:

curl -v 
    -X POST 
    -H "Authorization: Bearer 1234-abcd-5678-efgh" 
    -H "Content-Type: application/json" 
    -d '{“channel”:“<channel type>”, 
       “identifiers”:[{“name”:“<name1>”,“value”:“<value1>”},
       {“name”:“<name2>”,“value”:“<value2>”}], 
       “events”:[{“code”:“<IBM code>”,“timestamp”:“<time>”, 
       “attributes”:[{“name”:“<name1>”,“value”:“<value1>”},
       {“name”:“<name2>”,“value”:“<value2>”, 
       "type":"<type>"}]}}' 
    <base URL>/v1/event

The following tables describe the various ways to structure the JSON payload to publish
events.

Request JSON: publish individual event
{
   "channel":"<channel type>",
   "identifiers":[
      {
         "name":"<UBX identifier name>",
         "value":"<value detected during the event>"
      },
      {
         "name":"<UBX identifier name>",
         "value":"<value detected during the event>"
      }
   ],
   "events":[
      {
         "code":"<UBX event code>",
         "timestamp":"<time ISO-8601 format>",
         "attributes":[
            {
               "name":"<attribute name>",
               "value":"<value detected during the event>",
               "type":"<data type>"
            }
         ]
      }
   ]
}
Request JSON: publish multiple events in a simple batch
{
   "events":[
      {
         "code":"<UBX event code>",
         "timestamp":"<time ISO-8601 format>",
         "channel":"<channel type>",
         "attributes":[
            {
               "name":"<attribute name>",
               "value":"<value detected during the event>",
               "type":"<data type>"
            },
            {
               "name":"<attribute name>",
               "value":"<value detected during the event>",
               "type":"<data type>"
            }
         ],
         "identifiers":[
            {
               "name":"<UBX identifier name>",
               "value":"<value detected during the event>"
            },
            {
               "name":"<UBX identifier name>",
               "value":"<value detected during the event>"
            }
         ]
      },
      {
         "code":"<UBX event code>",
         "timestamp":"<time ISO-8601 format>",
         "channel":"<channel type>",
         "attributes":[
            {
               "name":"<attribute name>",
               "value":"<value detected during the event>",
               "type":"<data type>"
            },
            {
               "name":"<attribute name>",
               "value":"<value detected during the event>",
               "type":"<data type>"
            }
         ],
         "identifiers":[
            {
               "name":"<UBX identifier name>",
               "value":"<value detected during the event>"
            }
         ]
      }
   ]
} 

Request JSON: publish multiple related events in a compound batch

{
   "eventbatch":[
      {
	  "channel":"<channel type>",
         "identifiers":[
            {
               "name":"<UBX identifier name>",
               "value":"<value detected during the event>",
            },
            {
               "name":"<UBX identifier name>",
               "value":"<value detected during the event>",
            }
         ],
         "events":
			[
            {
               "code":"<UBX event code>",
               "timestamp":"<time ISO-8601 format>",
               "attributes":[
                  {
                     "name":"<attribute name>",
                     "value":"<value detected during the event>"
                  },
                  {
                     "name":"<attribute name>",
                     "value":"<value detected during the event>"
                  }
               ]
            },
            {
               "code":"<UBX event code>",
               "timestamp":"<time ISO-8601 format>",
               "attributes":[
                  {
                     "name":"<attribute name>",
                     "value":"<value detected during the event>",
                     "type":"<data type>"
                  },
                  {
                     "name":"<attribute name>",
                     "value":"<value detected during the event>",
                     "type":"<data type>"
                  },
                  {
                     "name":"<attribute name>",
                     "value":"<value detected during the event>",
                     "type":"<data type>"
                  }
               ]
            }
         ]
      },

continued…

      {
         "identifiers":[
            {
               "name":"<UBX identifier name>",
               "value":"<value detected during the event>",
            }
         ],
         "events":[
            {
               "code":"<UBX event code>",
               "timestamp":"<time ISO-8601 format>",
               "attributes":[
                  {
                     "name":"<attribute name>",
                     "value":"<value detected during the event>",
                     "type":"<data type>"
                  },
                  {
                     "name":"<attribute name>",
                     "value":"<value detected during the event>",
                     "type":"<data type>"
                  }
               ]
            },
            {
               "code":"<UBX event code>",
               "timestamp":"<time ISO-8601 format>",
               "attributes":[
                  {
                     "name":"<attribute name>",
                     "value":"<value detected during the event>",
                     "type":"<data type>"
                  },
                  {
                     "name":"<attribute name>",
                     "value":"<value detected during the event>",
                     "type":"<data type>"
                  },
                  {
                     "name":"<attribute name>",
                     "value":"<value detected during the event>",
                     "type":"<data type>"
                  }
               ]
            }
         ]
      }
   ]
}

Identify the channel where the event occurred

You must specify the channel as the device or method that is used to perform the activity or interaction that is being reported as an event. For example, if you know that event was performed with a mobile phone, you might enter mobile as a value for channel.

When you publish events as a batch, you can define the channel at the batch level or at the event level, but not at both levels. Within an API call, define the channel at either the batch level or at the event level.

Property Use Data type Valid value Description
channel Required String As defined in your business systems. The method or device that was used to perform the event.

Identify the individual who initiated the event

If your business systems can provide values that identify the specific individual who initiated the event, enter the values in the identifiers section of the API. Provide the identifier values that you submitted in the call to the v1/endpoint API to register the
endpoint with UBX.

UBX treats each identifier name and value as a separate identifier. If you provide multiple identifier name-value pairs for an event, UBX treats them as two separate identifiers rather than two parts of the same identifier. If you have an identifier that has two parts (business unit ID + user ID within that business unit), then you combine those values into a single value. For example, {business unit id}:{user id}.

Property Use Data type Valid Value Description
name Required String As registered with UBX

Name of the identifier.

For example, mobile_login.

value Required String As received

The value that was entered during the event.

For example, jsmith@example.com.

Describe the events that you publish

Provide values that enable UBX to identify the event. UBX uses the attributes that you enter here to display the event attributes in the UBX user interface.

Property Use Data type Valid Value Description
code Required String As registered with UBX The value that was submitted during event registration. Example:
ibmcartPurchase.
timestamp Required String Time, in ISO-8601 format. Example: 2015-02-28T20:16:12Z.
name Required String As registered with UBX Name of the attribute, as defined in the v1/eventtype API Example:
orderTotal.
value Required String As received.

The value that was entered during the event.

Always passed as a string. The subscribing application must be able to recognize and convert the string.

Example: 125.53.

type Required String

String

Number

Boolean

Time in ISO-8601 format

The type of data that is provided by the event.

Example: number

Response

UBX public APIs return standard HTTP 1.1 response codes.

When you call v1/event, you must specify the event channel and event identifiers. You can specify channel and identifiers at the batch level or at the event level. The call returns an error under the following conditions:

  • You specified identifiers at the batch level and the event level.
  • You did not specify a channel.
  • You specified a channel at the batch level and at the event level.

POST /v1/eventtype

Call POST v1/eventtype to register the events that an endpoint publishes to UBX.

About this API

Call POST v1/eventtype to declare the types of event data that an endpoint provides.

Make a separate API call for each type of event data that the endpoint provides. Because you must register events separately for each UBX user account, you must register events each time a UBX user requests a new endpoint connection.

IBM defines various types of typical business event types. For each event type, it defines a broad range of attributes that you can use to describe the event. Such events are considered IBM recognized events. UBX is designed to expect the types of data that recognized events provide.

You can also register event types that are not on the list of recognized events. IBM considers such events to be custom events. You create a custom event by registering an event type that is not one of the IBM recognized events, or if you define an attribute for a recognized event that is not one of the attributes that IBM has defined for the recognized event. Contact IBM before you attempt to register a custom event.

Note: IBM recognized events are not registered for an endpoint and UBX account by default. You must call POST v1/eventtype to register IBM recognized events and custom events.

You provide the following information when you register an event with UBX.

  • Event code.

    Every event must have a unique event code. UBX defines event codes for various recognized events that to describe typical customer actions. You can define custom event codes for events that are not IBM recognized events, but you cannot use an event code that IBM already uses for recognized events.

  • Name of the event.

    UBX uses the name that you enter to display the event as an option to business users in the UBX user interface.

  • Brief description of the event.

    UBX displays the description in the UBX user interface.

  • The namespace for the event.
  • The version of the event.
  • Registration type of the event.
  • Description of the event attributes that you can provide as an event publisher.

When you register the event with UBX, you indicate the attributes that your business application can observe and provide a value. Some attributes are required. Some attributes are strongly recommended. Still others are optional. Other than the required attributes, you do not need to commit to providing data for every possible event attribute.

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 POST 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -H "Content-Type: application/json" 
  -d '{“code” : “<IBM event code>”,“name” : “<event name>”, 
      “description” : “<brief description>”}' 
  <base URL>/v1/eventtype

The following table describes the JSON payload of the call.

JSON

Requirements

(See notes below)

{
   "code" : "<event code>",
   "name" : "<event name>",
   "description" : "<text>",
   "namespace" : "<namespace>",
   "version" : "<event catalog version>",
   "registrationType" : "<string>",

A.

Identify and describe the event type.

   "attributes":
   [
      {
      "name" : "<attribute name>",
      "type" : "<data type>"
      }
   ]
}

B.

Specify the event attributes that you provide as an event publisher.

A: Identify and describe the event type

Provide information that UBX requires to identify the event and to display and describe the event in the UBX user interface.

Property Use Data type Valid value Description
code Required String As provided by IBM A value that IBM provides to uniquely identify the event. Example:
ibmcartPurchase.
name Required String As defined in the endpoint application The value that you enter here becomes the event display name in the UBX user interface.
Example: orderTotal.
description Optional String As defined in the endpoint application The value that you enter here becomes the event description in the UBX user interface.
namespace Optional String As defined in the endpoint application Default: "com.ibm.commerce.ubx"

Enter a different namespace if you define a custom event with a code that duplicates an event
code that is already registered with UBX.

version Optional Number As defined in the endpoint application Default: 1

Specify the version of the UBX event catalog. Enter as a
number only.

Currently, version 1 is the only available version of the catalog.

registrationType Optional String PUBLISH

SUBSCRIBE

Default: PUBLISH

PUBLISH: Identifies an event
that the registering endpoint publishes to UBX.

SUBSCRIBE: Identifies
an event that the registering endpoint receives from UBX.

B: Specify event attributes

In the attributes section, provide values that describe the event. Provide the names of the attributes that the event provides, and indicate the type of data that each attribute delivers. The UBX user interface uses the values that you provide to describe the event.

Enter as many attribute descriptions as your business systems can provide for the event.

Property Use Data type Valid value Description
name Required String As registered with UBX Name of the attribute. Example: orderTotal.
type Required String

String

Number

Boolean

Time in ISO-8601 format

The type of data that is provided by the event.

Example: number

Response

UBX public APIs return standard HTTP 1.1 response codes.

The POST /v1/eventtype returns responses as follows.

Code Description

200 – 299

Success. The event type is registered with UBX for the endpoint.

400 – 499

There is a problem with the API request. Examine the request for errors.

500 – 599

System error. Contact IBM for assistance.

GET /v1/eventtype

For a specific event producer or consumer endpoint, this API identifies and describes all of the event types that are registered with UBX by the endpoint.

About this API

This API returns a list of all types of events that are registered for a specific endpoint. You can specify either an event producer or event consumer in the API call.

Request

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

The authentication key that you include as the authorization bearer in the API call specifies the endpoint.

Request format (as a curl command):

curl -v 
    -X GET 
    -H "Authorization: Bearer <endpoint authentication key>" 
    -H "Content-Type: application/json" 

    https://<base URL>/v1/eventtype

Response

The API returns a JSON payload that describes every event type that is registered with UBX by the
endpoint

[
   {
    "code": "<event code>",
    "version": <IBM event catalog version>,
    "namespace": "<namespace>",
    "name": "<event name>",
    "description": "<text>",
    "attributes": 
      [  
       {
       "name": "<attribute name>",
       "type": "<data type>"
       }
      ],
    "registrationType": "<endpoint type>"
   }
]
Property Use Data type Valid value Description
code Required String As provided by IBM A value that IBM provides to uniquely identify the event. Example:
ibmcartPurchase.
version Optional Number As defined in the endpoint application Default: 1

Specify the version of the UBX event catalog. Enter as a
number only.

Currently, version 1 is the only available version of the catalog.

namespace Optional String As defined in the endpoint application Default: "com.ibm.commerce.ubx"

Enter a different namespace if you define a custom event with a code that duplicates an event
code that is already registered with UBX.

name Required String As defined in the endpoint application The value that you enter here becomes the event display name in the UBX user interface.
Example: orderTotal.
description Optional String As defined in the endpoint application The value that you enter here becomes the event description in the UBX user
interface.
attributes Optional Attributes that are included in the definition of the event types that are registered to the
endpoint.
name

(attribute name)

Required String As registered with UBX Name of the attribute. Example: orderTotal.
type Required String

String

Number

Boolean

Time in ISO-8601 format

The type of data that is provided by the event.

Example: number

registrationType Optional String PUBLISH

SUBSCRIBE

Default: PUBLISH

PUBLISH: Identifies an event
that the registering endpoint publishes to UBX.

SUBSCRIBE: Identifies
an event that the registering endpoint receives from UBX.

GET /v1/eventtype/subscribed

For a specific event producer endpoint, this API lists events produced by the endpoint that are currently being consumed by another endpoint. The list does not provide descriptive information for each event type.

About this API

The API returns a simple list of event codes that identify the types of events that the endpoint produces and that are subscribed to by another endpoint. Event types that have no subscribers are omitted from the return.

Request

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

The authentication key that you include as the authorization bearer in the API call specifies the endpoint. Specify an authentication key for an event producer endpoint. Such endpoints are also called event publishers.

Request format (as a curl command):

curl -v 
    -X GET 
    -H "Authorization: Bearer <endpoint authentication key>" 
    -H "Content-Type: application/json" 

    <base URL>/v1/eventype/subscribed

Response

The API returns a list of event codes that specify the event types that are registered with UBX by the endpoint.

[<event code 1>,<event code 2>,<event code n>]

GET /v1/eventtype/subscribed/producer

For a specific event producer endpoint, this API identifies and describes events produced by the endpoint that are currently being consumed by another endpoint. The return includes descriptive information for each event type.

About this API

This API returns a list and description of all event types that are provided by a specified event producer and that are subscribed to by one or more event consumer endpoints. Event types that have no subscribers are omitted from the return.

The authentication key that you include as the authorization bearer in the API call specifies the event producer endpoint. Such endpoints are also called event publishers.

Request

Direct the API call to https://api-01.ubx.ibmmarketingcloud.com/.

The authentication key that you include as the authorization bearer in the API call specifies the endpoint. Specify an authentication key for an event publisher.

Request format (as a curl command):

curl -v 
    -X GET 
    -H "Authorization: Bearer <endpoint authentication key>" 
    -H "Content-Type: application/json" 

    https://api-01.ubx.ibmmarketingcloud.com/v1/eventype/subscribed/producer

Response

The API returns a JSON payload that describes every event type that the endpoint produces and that are also consumed by another endpoint. The payload does not include event types that have no subscribers.

[
   {
    "code": "<event code 1>",
    "version": <IBM event catalog version>,
    "namespace": "<namespace>",
    "name": "<event name>",
    "description": "<text>",
    "attributes": 
      [  
       {
       "name": "<attribute name 1>",
       "type": "<data type>"
       }
	   {
       "name": "<attribute name 2>",
       "type": "<data type>"
       }
	   {
       "name": "<attribute name n>",
       "type": "<data type>"
       }
      ],
    "registrationType": "<endpoint type>"
   }
   {
    "code": "<event code 2>",
    "version": <IBM event catalog version>,
    "namespace": "<namespace>",
    "name": "<event name>",
    "description": "<text>",
    "attributes": 
      [  
       {
       "name": "<attribute name>",
       "type": "<data type>"
       }
      ],
    "registrationType": "<endpoint type>"
   }
   {
    "code": "<event code n>",
    "version": <IBM event catalog version>,
    "namespace": "<namespace>",
    "name": "<event name>",
    "description": "<text>",
    "attributes": 
      [  
       {
       "name": "<attribute name>",
       "type": "<data type>"
       }
      ],
    "registrationType": "<endpoint type>"
   }
]
Property Use Data type Valid value Description
code Required String As provided by IBM A value that IBM provides to uniquely identify the event. Example:
ibmcartPurchase.
version Optional Number As defined in the endpoint application Default: 1

Specify the version of the UBX event catalog. Enter as a
number only.

Currently, version 1 is the only available version of the catalog.

namespace Optional String As defined in the endpoint application Default: "com.ibm.commerce.ubx"

Enter a different namespace if you define a custom event with a code that duplicates an event
code that is already registered with UBX.

name Required String As defined in the endpoint application The value that you enter here becomes the event display name in the UBX user interface.
Example: orderTotal.
description Optional String As defined in the endpoint application The value that you enter here becomes the event description in the UBX user interface.
attributes Optional Attributes that are included in the definition of the event types that are registered to the endpoint.
name

(attribute name)

Required String As registered with UBX Name of the attribute. Example: orderTotal.
type Required String

String

Number

Boolean

Time in ISO-8601 format

The type of data that is provided by the event.

Example: number

registrationType Optional String PUBLISH

SUBSCRIBE

Default: PUBLISH

PUBLISH: Identifies an event
that the registering endpoint publishes to UBX.

SUBSCRIBE: Identifies
an event that the registering endpoint receives from UBX.

GET /v1/eventtype/subscribed/consumer

For a specific event consumer endpoint, this API identifies and describes the events that the endpoint subscribes to.

About this API

This API returns a list and description of all event types that the endpoint subscribes to from any event producer endpoint.

Request

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

The authentication key that you include as the authorization bearer in the API call specifies the endpoint. Specify an authentication key for an event subscriber.

You can include the optional URL parameters ?extrafields=provider,publisher in this call to return more information about the endpoint provider and publisher of each event.

Request format (as a curl command):

curl -v 
    -X GET 
    -H "Authorization: Bearer <endpoint authentication key>" 
    -H "Content-Type: application/json" 

    <base URL>/v1/eventtype/subscribed/consumer?extrafields=provider,publisher

Response

The API returns a JSON payload that describes every event type that the endpoint subscribes to, from various event publishing endpoints.

[
   {
    "code": "<event code 1>",
    "version": <IBM event catalog version>,
    "namespace": "<namespace>",
    "name": "<event name>",
    "description": "<text>",
    "attributes": [  
       {
       "name": "<attribute name 1>",
       "type": "<data type>"
       },
       {
       "name": "<attribute name 2>",
       "type": "<data type>"
       },
        {
       "name": "<attribute name n>",
       "type": "<data type>"
       }
      ],
    "registrationType": "<endpoint type>",
    "publisher":"<event publisher name>",
    "provider":"<event provider name>"
   },
   {
    "code": "<event code 2>",
    "version": <IBM event catalog version>,
    "namespace": "<namespace>",
    "name": "<event name>",
    "description": "<text>",
    "attributes":[  
       {
       "name": "<attribute name>",
       "type": "<data type>"
       }
      ],
    "registrationType": "<endpoint type>"
    "publisher":"<event publisher name>",
    "provider":"<event provider name>"
   },
   {
    "code": "<event code n>",
    "version": <IBM event catalog version>,
    "namespace": "<namespace>",
    "name": "<event name>",
    "description": "<text>",
    "attributes": 
      [  
       {
       "name": "<attribute name>",
       "type": "<data type>"
       }
      ],
    "registrationType": "<endpoint type>"
    "publisher":"<event publisher name>",
    "provider":"<event provider name>"
   }
]
Property Use Data type Valid value Description
code Required String As provided by IBM A value that IBM provides to uniquely identify the event. Example:
ibmcartPurchase.
version Optional Number As defined in the endpoint application Default: 1

Specify the version of the UBX event catalog. Enter as a number only.

Currently, version 1 is the only available version of the catalog.

namespace Optional String As defined in the endpoint application Default: "com.ibm.commerce.ubx"

Enter a different namespace if you define a custom event with a code that duplicates an event code that is already registered with UBX.

name Required String As defined in the endpoint application The value that you enter here becomes the event display name in the UBX user interface.
Example: orderTotal.
description Optional String As defined in the endpoint application The value that you enter here becomes the event description in the UBX user
interface.
attributes Optional Attributes that are included in the definition of the event types that are registered to the
endpoint.
name

(attribute name)

Required String As registered with UBX Name of the attribute. Example: orderTotal.
type Required String

String

Number

Boolean

Time in ISO-8601 format

The type of data that is provided by the event.

Example: number

registrationType Optional String PUBLISH

SUBSCRIBE

Default: PUBLISH

PUBLISH: Identifies an event
that the registering endpoint publishes to UBX.

SUBSCRIBE: Identifies
an event that the registering endpoint receives from UBX.

publisher Optional String

As registered with UBX

The name of the event publisher endpoint. There can be multiple events associated with a single event publisher endpoint.

provider Optional String

As registered with UBX

The endpoint provider name, also known as an application. A single endpoint provider can have multiple endpoints associated with it.

PUT /v1/eventtype/attributes/publisher/{id}

Call PUT /v1/eventtype/attributes/publisher/{id} update the attributes that are defined for a specific event publishing endpoint.

About this API

Call PUT /v1/eventtype/attributes/publisher/{id} to replace the list of event attributes that are registered by an endpoint that publishes a recognized event. When an event publisher registers an event with UBX, it must specify which event attributes it can support.
Calling this API gives the endpoint the ability to add or remove attributes by providing an updated list of attributes.

Because you must register events separately for each UBX user account, if you subsequently update the event definition, you must update event attributes for each UBX customer account that registered the endpoint as an event publisher.

Note: Do not call this API to update attributes for an endpoint that subscribes to events. To update an event subscriber endpoint, call PUT /v1/eventtype/attributes/subscriber/{id}

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 POST 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -H "Content-Type: application/json" 
  -d '{“code” : “name” : “<attribute name>”,“type” : “<data type>”}' 
  <base URL>/v1/eventtype/attributes/
  publisher/<endpoint ID>

The following table describes the JSON payload of the call.

JSON

Requirements

(See notes below)

[
  {
  "name" : "<attribute name>",
  "type" : "<data type>" 
  }
  {
  "name" : "<attribute name>",
  "type" : "<data type>" 
  }
]

A.

Specify a new set of event attributes that you want to update.

A: Specify a new set of event attributes

Provide information that defines the updated set of event attributes for the event publisher endpoint. Define the name and data type for as many attributes as necessary.

Property Use Data type Valid value Description
name Required String As registered with UBX Name of the attribute. Example: orderTotal.
type Required String

String

Number

Boolean

Time in ISO-8601 format

The type of data that is provided by the event.

Example: number.

PUT /v1/eventtype/attributes/subscriber/{id}

Call PUT /v1/eventtype/attributes/subscriber/{id} update the attributes that are defined for a specific event subscriber endpoint.

About this API

Call PUT /v1/eventtype/attributes/subscriber/{id} to replace the list of event attributes that are registered by an endpoint that subscribes to a recognized event. If an event publisher changes the event attributes it supports, calling this API gives a subscribing endpoint the ability to match the changes.

Because you must register events separately for each UBX user account, if event definitions change, you must update event attributes for each UBX customer account that registered the endpoint as an event subscriber.

Note: Do not call this API to update attributes for an endpoint that publishes events. To update an event publisher endpoint, call PUT /v1/eventtype/attributes/publisher/{id}

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 POST 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -H "Content-Type: application/json" 
  -d '{“code” : “name” : “<attribute name>”,“type” : “<data type>”}' 
  <base URL>/v1/eventtype/attributes/
  subscriber/<endpoint ID>

The following table describes the JSON payload of the call.

JSON

Requirements

(See notes below)

[
  {
  "name" : "<attribute name>",
  "type" : "<data type>" 
  }
  {
  "name" : "<attribute name>",
  "type" : "<data type>" 
  }
]

A.

Specify a new set of event attributes that you want to update.

A: Specify a new set of event attributes

Provide information that defines the updated set of event attributes for the event subscriber endpoint. Define the name and data type for as many attributes as necessary.

Property Use Data type Valid value Description
name Required String As registered with UBX Name of the attribute. Example: orderTotal.
type Required String

String

Number

Boolean

Time in ISO-8601 format

The type of data that is provided by the event.

Example: number.

DELETE /v1/eventtype/{code}

Call DELETE /v1/eventtype/{code} to remove a specific event type from the list of event types that are registered to an endpoint.

About this API

This API removes an event type registration from the endpoint that is associated with the authentication key that is included as the authorization bearer in the API call.

Request

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

Request format (as a curl command):

curl -v 
    -X DELETE 
    -H "Authorization: Bearer <endpoint authentication key>" 
    -H "Content-Type: application/json" 
	
    https:// <base URL>/v1/eventtype/<event code>

Response

UBX public APIs return standard HTTP 1.1 response codes.

POST /v1/endpoint/{endpointId}/segments provides responses as follows.

Code Description

200

true: The event type registration is removed from the endpoint.

false: The event type registration is not removed.

403

Not authorized.

500 – 599

System error. Contact IBM for assistance.

GET /v1/eventfiles

Call to UBX to return the names of up to 10 files that contain event data.

About this API

Call GET /v1/eventfiles as part of a series of calls to copy files from UBX to a directory that is maintained by an event Pull subscriber endpoint. The call returns up to 10 file names. Each file contains metadata and attributes for events that were collected and published to UBX by an event publisher endpoint.

Request

You must specify the endpoint-level authentication key 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.

To return less than 10 files per API call, add the numFiles query parameter to the API call. Specify the parameter as https://<baseURL>/v1/eventfiles?numFiles=<number>, where <number> is the maximum number of files to return. If less than the maximum number of files are available in UBX, UBX returns all available files.

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

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

Response

UBX public APIs return standard HTTP 1.1 response codes. For a successful call, the response
returns a list of file names.

The call returns a maximum of 10 file names.

GET /v1/eventfiles/<filename>

Call to UBX to copy a file that contains event data from UBX to a directory.

About this API

Call GET /v1/eventfiles/<filename> as part of a series of calls to copy files from UBX to a directory that is maintained by an event Pull subscriber endpoint. Specify a file name that is returned by v1/eventfiles as a parameter of the call.

The call returns the contents of the specified file.

Request

You must specify the endpoint-level 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 (by using curl) to retrieve details for applications that were created with the specified authentication key:

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

Response

UBX public APIs return standard HTTP 1.1 response codes.

In a successful call, the response returns the contents of the specified file as an application/octet-stream. You must save and process the response as appropriate for your business solution.

Completing the API call does not remove the events file from UBX. Subsequent calls to GET v1/eventfiles will list the file as unavailable file. To avoid potential confusion in subsequent event file requests, clean up the file store by calling DELETE v1/eventfile/<filename> to remove the source event file after you retrieve all of the files.

DELETE /v1/eventfiles/<filename>

Call to UBX to remove a specific file from storage in UBX.

About this API

After you finish copying an events file from UBX, you can call DELETE /v1/eventfiles/<filename> to remove the file. It is no longer needed.

If you do not remove the file from UBX by making the DELETE call, GET /v1/eventfiles continues to return the file name that will prevent the client from discovering and processing other files.

Request

You must specify an endpoint-level authentication key as the authorization bearer.

The file name is the name of a file that contains event data but that is no longer needed because you copied the file with a call to GET /v1/eventfiles/<filename>.

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 (by using curl) to remove the specified UBX application:

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

Response

UBX public APIs return standard HTTP 1.1 response codes.

GET /v1/endpoint/{endpointId}/eventinfo

Call GET /v1/endpoint/{endpointId}/eventinfo to use an authentication key that is only used by browsers to send events.

About this API

The API allows you to use a special authentication key that sends events directly from a browser when it is triggered by the JavaScript on your website.

To use this API, you must use an authorization header with your endpoint authorization key.

The GET /v1/endpoint/{endpointId}/eventinfo call only needs to be done once. After you make this call, you must use the eventAuthKey in the /v1/customEvent API.

Request

The following is an example curl request to trigger the endpoint/{endpointId}/eventinfo API.

https://ubx-01.ibmmarketingcloud.com/v1/endpoint/{endpointID}/eventinfo

Response

UBX public APIs return a simple JSON object.

{    
          "endpointId": ...,    
          "eventAuthKey": ...  
}

PUT /v1/subscription/notification

Use the v1/subscription/notification API to register a syndication
change notification with UBX.

About this API

Call <base URL>/v1/subscription/notification to instruct UBX to monitor subscriptions for a specified endpoint and report all changes immediately as an HTTP call.

/v1/subscription/notification registers a request for UBX to report changes to subscriptions that are associated with a specific endpoint. The request must provide the following information.

  • The authentication key for the endpoint.
  • A notification key
  • URL that receives the notification.

Optionally, the API call can include an expanded JSON payload to specify authentication information if authentication is required to connect to the notification URL.

JSON: No authentication

For sending notifications to endpoints that do not require authenticated access, structure the JSON payload as shown in this example.

{
   "notificationKey":"<key value>", 
   "notificationURL" : "<URL for receiving notifications>"
} 

You can define a notification key to include additional information with the subscription notification. The notification key can be any string value. For example, you might track new user event requests by entering a value that specifies an account or organization.

UBX sends the notifications as an HTTP call to URL that you specify in the notificationURL property.

Property Use Type Value Description
notificationKey Optional String As required by your business process. Added string that you define. UBX includes the value with each notification.
notificationURL Required URL URL Enter the URL where you want UBX to send the subscription notifications.

JSON: API Key authentication

For sending notifications to endpoints that require an API key to authenticate, structure the JSON payload as shown in this example. Provide the API key that UBX must submit in the header of the HTTP call that indicates a subscription change.

{ 
   "authentication": 
      { "authType" : "APIKey", 
	    "APIKey", "<api key>" 
	  }, 
	"notificationKey":"key value", 
	"notificationURL" : "<URL for receiving notifications>"
} 
Property Use Type Value Description
authType Required String APIKey To specify authentication with an API key, specify
APIKey.
APIKey Required String As required by your business systems. Provide the key that UBX must submit when it sends a subscription
notification.

JSON: HTTP basic authentication

For sending notifications to endpoints that require basic HTTP authentication, structure the JSON payload as shown in this example. Provide a user ID and password that UBX must submit in the header of the HTTP call that indicates a subscription change.

{ 
   "authentication": 
      { 
	    "authType" : "Basic", 
	    "userId" : "<user id>", 
	    "password" : "<password>" 
	  }, 
   "notificationKey":"<key value>", 
   "notificationURL" : "<URL for receiving notifications>"
} 
Property Use Type Value Description
authType Required String Basic To specify basic HTTP authentication, specify
Basic.
userId Required String As required by your business systems. Provide the user ID that UBX must submit when it sends a subscription notification.
password Required String As required by your business systems. Provide the password that UBX must submit when it sends a subscription notification.

JSON: OAuth authentication

For sending notifications to endpoints that require basic OAuth authentication, structure the JSON payload as shown in this example.

{ 
   "authentication": 
      { 
	  "authType" : "OAuth", 
	  "authURL": "<URL for the OAuth access token>", 
	  "clientID"" : "<Oauth client Id>",  
	  "clientSecret" : <Oauth client secret>", 
	  "refreshToken":  "<refresh token>"
	  }, 
   "notificationKey":"<key value>", 
   "notificationURL" : "<URL for receiving notifications>"
}
Property Use Type Value Description
authType Required String OAuth To specify OAuth authentication, specify
OAuth.
authURL Required URL As required Provide the user URL that UBX must use to generate an OAuth access token when it sends a subscription notification.
clientID Required String As required Provide the OAuth clientID that UBX must submit when it sends a subscription notification.
clientSecret Required String As required Provide the OAuth client secret that UBX must submit when it sends a subscription notification.
refreshToken Required String As required Provide the OAuth refresh token that UBX must submit when it sends a subscription notification.

JSON: OAuth with refresh token only

For sending notifications to endpoints that require basic OAuth authentication, structure the JSON payload as shown in this example. This example assumes that you were able to provide the OAuth clientID and clientSecret to IBM separately during the partner provisioning process. As a result, you need only to pass the refresh token in the API
call.

During the provisioning process, IBM provides you with a Supplier key after you provide IBM with a client id and client secret. You must include the Supplier key in the API call.

{ 
   "authentication": 
      { 
	  "authType" : "OAuthRefreshTokenOnly", 
	  "authURL" : "<URL for the OAuth access token>", 
	  "supplierKey" : "<IBM-provided key>", 
	  "refreshToken" : "<refresh token>"
	  }, 
   "notificationKey" :"<key value>", 
   "notificationURL" : "<URL for receiving notifications>"
} 
Property Use Type Value Description
authType Required String OAuthRefreshTokenOnly To specify OAuth authentication that does not require sending ClientID and clientSecret, specify OAuthRefreshTokenOnly.
authURL Required URL As required Provide the user URL that UBX must use to generate an OAuth access token when it sends a subscription notification.
supplierKey Required String As provided by IBM Enter the Supplier key that IBM provided to you during account provisioning.
refreshToken Required String As required Provide the OAuth refresh token that UBX must submit when it sends a subscription notification.

DELETE /v1/subscription/notification

Remove a subscription notification that is registered for an endpoint.

About this API

Subscription notifications are created for specific endpoints that are registered within a specific UBX user account. When you stop a subscription notification you are stopping notifications for a specific endpoint and UBX user account. You must submit the authentication key that was provided by the UBX user account to register the endpoint with UBX.

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" 
  -d 
   <base URL>/v1/subscription/notification

Response

UBX public APIs return standard HTTP 1.1 response codes.

1 comment on"Event API"

  1. Danylo Baran August 06, 2018

    Hi! We are developing node.js application which sends events to IBM UBX Event API. We have an issue with calculating size of request body (Event size) and receiving response “413 – Event size 91644 exceeds the maximum allowed of 80000 bytes” when actual body size is 56424 which also sent in “Content-Length” header. Can you explain how to calculate the size of events correctly?

Join The Discussion

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