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 Exchange user account, you must register events each time an Exchange user requests a new endpoint connection.

Acoustic 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 Acoustic recognized events. Exchange 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. Acoustic considers such events to be custom events. You create a custom event by registering an event type that is not one of the recognized events, or if you define an attribute for a recognized event that is not one of the attributes that Acoustic has defined for the recognized event. Contact Support before you attempt to register a custom event.

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

• Event code.

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

• Name of the event.

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

• Brief description of the event.

  Exchange displays the description in the 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 Exchange, 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 Exchange 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.

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

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

A. Identify and describe the event type

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

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 Exchange 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.

Response

Exchange public APIs return standard HTTP 1.1 response codes.

The POST /v1/eventtype returns responses as follows.