Use Acoustic Exchange event API to register and publish events. Acoustic Exchange also provides API to monitor how
Acoustic Exchange customers subscribe to events that you publish through Acoustic Exchange.
POST /v1/event
Use the v1/event API to publish events from an event publisher endpoint to Acoustic Exchange. 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 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.
Request JSON: publish individual event |
---|
|
Request JSON: publish multiple events in a simple batch |
---|
|
Request JSON: publish multiple related events in a compound batch Option 1. The channel inside events |
---|
Or option 2: Channel at the top, but outside of eventbatch |
|
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 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}.
Property | Use | Data type | Valid Value | Description |
---|---|---|---|---|
name | Required | String | As registered with Acoustic Exchange |
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 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.
Property | Use | Data type | Valid Value | Description |
---|---|---|---|---|
code | Required | String | As registered with Acoustic Exchange | 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 Acoustic Exchange | 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
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.
POST /v1/eventtype
Call POST v1/eventtype to register the events that an endpoint publishes to Acoustic Exchange.
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.
JSON |
Requirements (See notes below) |
---|---|
|
A. Identify and describe the event type. |
|
B. Specify the event attributes that you provide as an event publisher. |
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.
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 Acoustic Exchange 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 Acoustic Exchange 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 |
version | Optional | Number | As defined in the endpoint application | Default: 1
Specify the version of the Acoustic Exchange event catalog. Enter as a Currently, version 1 is the only available version of the catalog. |
registrationType | Optional | String | PUBLISH
SUBSCRIBE |
Default: PUBLISH
PUBLISH: Identifies an event SUBSCRIBE: Identifies |
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.
Property | Use | Data type | Valid value | Description |
---|---|---|---|---|
name | Required | String | As registered with Acoustic Exchange | 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
Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 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
|
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 Acoustic Exchange event catalog. Enter as a 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 |
name | Required | String | As defined in the endpoint application | The value that you enter here becomes the event display name in the Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange | 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 SUBSCRIBE: Identifies |
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 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.
|
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.
|
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 Acoustic Exchange event catalog. Enter as a 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 |
name | Required | String | As defined in the endpoint application | The value that you enter here becomes the event display name in the Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange | 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 SUBSCRIBE: Identifies |
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 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.
|
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 Acoustic Exchange 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 Acoustic Exchange. |
name | Required | String | As defined in the endpoint application | The value that you enter here becomes the event display name in the Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange | 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 SUBSCRIBE: Identifies |
publisher | Optional | String |
As registered with Acoustic Exchange |
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 Acoustic Exchange |
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 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.
JSON |
Requirements (See notes below) |
---|---|
|
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 Acoustic Exchange | 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 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.
JSON |
Requirements (See notes below) |
---|---|
|
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 Acoustic Exchange | 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. |
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 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.
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 Acoustic Exchange 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 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.
GET /v1/eventfiles/<filename>
Call to Acoustic Exchange to copy a file that contains event data from Acoustic Exchange to a directory.
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.
DELETE /v1/eventfiles/<filename>
Call to Acoustic Exchange to remove a specific file from storage in Acoustic Exchange.
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.
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
Acoustic Exchange 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 Acoustic Exchange.
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.
|
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.
Property | Use | Type | Value | Description |
---|---|---|---|---|
notificationKey | Optional | String | As required by your business process. | Added string that you define. Acoustic Exchange includes the value with each notification. |
notificationURL | Required | URL | URL | Enter the URL where you want Acoustic Exchange 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 Acoustic Exchange must submit in the header of the HTTP call that indicates a subscription change.
|
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 Acoustic Exchange 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 Acoustic Exchange must submit in the header of the HTTP call that indicates a subscription change.
|
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 Acoustic Exchange must submit when it sends a subscription notification. |
password | Required | String | As required by your business systems. | Provide the password that Acoustic Exchange 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.
|
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 Acoustic Exchange must use to generate an OAuth access token when it sends a subscription notification. |
clientID | Required | String | As required | Provide the OAuth clientID that Acoustic Exchange must submit when it sends a subscription notification. |
clientSecret | Required | String | As required | Provide the OAuth client secret that Acoustic Exchange must submit when it sends a subscription notification. |
refreshToken | Required | String | As required | Provide the OAuth refresh token that Acoustic Exchange 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.
|
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 Acoustic Exchange 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 Acoustic Exchange 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 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.
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?