Event API

Before you begin

The identifiers that you specify in calls to v1/event must be registered with Acoustic Exchange for use by your Acoustic Exchange 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 Acoustic Exchange for use by your Acoustic Exchange account. The event attributes that you specify must also be registered with Acoustic Exchange. To register event types and attributes that you support, call POST v1/eventtype.

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

About this API

You can publish events individually or in batches. Acoustic Exchange 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.

Events

Request

Direct the API call to the base URL that is assigned to your Acoustic Exchange 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.

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

{
   "events":[
      {
         "code":"<Acoustic Exchange 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":"<Acoustic Exchange identifier name>",
               "value":"<value detected during the event>"
            },
            {
               "name":"<Acoustic Exchange identifier name>",
               "value":"<value detected during the event>"
            }
         ]
      },
      {
         "code":"<Acoustic Exchange 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":"<Acoustic Exchange identifier name>",
               "value":"<value detected during the event>"
            }
         ]
      }
   ]
} 

{
    "provider" : "IBM",
    "eventbatch": [
   {
          
           "identifiers" :[
         {
               "name" : "<UBX identifier name>",
               "value" : "<value detected during the event>"}
    ],
    "events":
    [
        {
           "code" : "<UBX event code>",
           "channel" : "<channel type>",
            "attributes" :
            [
                { "name": "<UBX attribute name>, <value detected during the event>" },
                { "name": "<UBX attribute name>, <alue detected during the event>" },
                { "name": "<UBX attribute name>, <value detected during the event>" },       
            ]
        }
    ]
},
{ "identifiers" :
    [
     {
               "name" : "<UBX attribute name>",
               "value" : "<value detected during the event>",
               "channel" : "<channel type>",
               "provider" : "IBM"    }
    ],
    "events":
    [
        {
            "code" : "<UBX event code>",
            "channel" : "<channel type>",
            "attributes" :
            [
                { "name": "<UBX attribute name>, <value detected during the event>" },
                { "name": "<UBX attribute name>, <value detected during the event>" },
                { "name": "<UBX attribute name>, <value detected during the event>" },       
            ]
        }
    ]
}

  ]
}

{
    "provider" : "IBM",
   "channel" : "<channel type>",
    "eventbatch": [
   { "identifiers" :
    [
         {
               "name" : "<UBX identifier name>",
               
               "value" : "<value detected during the event>"}
    ],
    "events":
    [
        {
           "code" : "<UBX event code>",
            "attributes" :
            [
                { "name": "<UBX attribute name>, <value detected during the event>" },
                { "name": "<UBX attribute name>, <value detected during the event>" },
                { "name": "<UBX attribute name>, <value detected during the event>" },       
 
            ]
        }
    ]
},
{ "identifiers" :
    [
     {
               "name" : "<UBX identifier name>",
               "value" : "<value detected during the event>",
               "channel" : "<channel type>",
               "provider" : "IBM"    }
    ],
    "events":
    [
        {
            "code" : "<UBX event code>",
            "attributes" :
            [
                { "name": "<UBX attribute name>, <value detected during the event>" },
                { "name": "<UBX attribute name>, <value detected during the event>" },
                { "name": "<UBX attribute name>, <value detected during the event>" },       
            ]
        }
    ]

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.

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

Acoustic Exchange treats each identifier name and value as a separate identifier. If you provide multiple identifier name-value pairs for an event, Acoustic Exchange 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}.

Describe the events that you publish

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

Response

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

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 Acoustic Exchange user account, you must register events each time a Acoustic Exchange 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. Acoustic 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. 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.

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

• Event code.

  Every event must have a unique event code. Acoustic 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 IBM recognized events, but you cannot use an event code that IBM already uses for recognized events.

• Name of the event.

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

• Brief description of the event.

  Acoustic Exchange displays the description in the Acoustic Exchange 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 Acoustic 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 Acoustic 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 Acoustic Exchange requires to identify the event and to display and describe the event in the Acoustic 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 Acoustic 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

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

The POST /v1/eventtype returns responses as follows.

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 Acoustic Exchange 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 Acoustic Exchange 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>"
   }
]

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 Acoustic Exchange 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 Acoustic Exchange by the endpoint.

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

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>"
   }
]

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 Acoustic Exchange 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>"
   }
]

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 Acoustic Exchange, 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 Acoustic Exchange user account, if you subsequently update the event definition, you must update event attributes for each Acoustic Exchange customer account that registered the endpoint as an event publisher.

Request

Direct the API call to the base URL that is assigned to your Acoustic 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” : “name” : “<attribute name>”,“type” : “<data type>”}' 
  <base URL>/v1/eventtype/attributes/
  publisher/<endpoint ID>

The following table describes the JSON payload of the call.

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

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.

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 Acoustic Exchange user account, if event definitions change, you must update event attributes for each Acoustic Exchange customer account that registered the endpoint as an event subscriber.

Request

Direct the API call to the base URL that is assigned to your Acoustic 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” : “name” : “<attribute name>”,“type” : “<data type>”}' 
  <base URL>/v1/eventtype/attributes/
  subscriber/<endpoint ID>

The following table describes the JSON payload of the call.

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

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.

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

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

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

About this API

Call GET /v1/eventfiles as part of a series of calls to copy files from Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange, Acoustic Exchange 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

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

About this API

Call GET /v1/eventfiles/<filename> as part of a series of calls to copy files from Acoustic Exchange 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 Acoustic Exchange 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

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

About this API

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

If you do not remove the file from Acoustic Exchange 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 Acoustic Exchange application:

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

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

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

Acoustic Exchange public APIs return a simple JSON object.

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

About this API

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

/v1/subscription/notification registers a request for Acoustic Exchange 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.

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

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 Acoustic Exchange 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>"
} 

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 Acoustic Exchange 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>"
} 

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>"
}

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>"
} 

About this API

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

Request

Direct the API call to the base URL that is assigned to your Acoustic Exchange 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

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.