Event API

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

POST /v1/event

Use the v1/event API to publish events from an event publisher endpoint to 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 Exchange for use by your 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 Exchange for use by your Exchange account. The event attributes that you specify must also be registered with 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. 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

Note: Exchange 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 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”:“<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>"
            }
         ]
      }
   ]
}

Request JSON: publish multiple events in a simple batch

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

Request JSON: publish multiple related events in a compound batch

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

  ]
}

{
    "provider" : "Acoustic",
   "channel" : "<channel type>",
    "eventbatch": [
   { "identifiers" :
    [
         {
               "name" : "<identifier name>",
               
               "value" : "<value detected during the event>"}
    ],
    "events":
    [
        {
           "code" : "<event code>",
            "attributes" :
            [
                { "name": "<attribute name>, <value detected during the event>" },
                { "name": "<attribute name>, <value detected during the event>" },
                { "name": "<attribute name>, <value detected during the event>" },       
 
            ]
        }
    ]
},
{ "identifiers" :
    [
     {
               "name" : "<identifier name>",
               "value" : "<value detected during the event>",
               "channel" : "<channel type>",
               "provider" : "Acoustic"    }
    ],
    "events":
    [
        {
            "code" : "<event code>",
            "attributes" :
            [
                { "name": "<attribute name>, <value detected during the event>" },
                { "name": "<attribute name>, <value detected during the event>" },
                { "name": "<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 Exchange.

Acoustic Exchange treats each identifier name and value as a separate identifier. If you provide multiple identifier name-value pairs for an event, 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 Exchange to identify the event. Exchange uses the attributes that you enter here to display the event attributes in the 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.
  ##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 Exchange user account, you must register events each time an Exchange user requests a new endpoint connection.

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

Note: Acoustic Exchange recognized events are not registered for an endpoint and Acoustic Exchange account by default. You must call POST v1/eventtype to register Acoustic Exchange recognized events and custom events. You provide the following information when you register an event with Acoustic 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 Acoustic recognized events, but you cannot use an event code that Acoustic 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. Exchange displays the description in the 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 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” : “<event code>”,“name” : “<event name>”, 
      “description” : “<brief description>”}' 
  <base URL>/v1/eventtype

The following table describes the JSON payload of the call.

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.

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

[
   {
    "code": "<event code>",
    "version": <event catalog version>,
    "namespace": "<namespace>",
    "name": "<event name>",
    "description": "<text>",
    "attributes": 
      [  
       {
       "name": "<attribute name>",
       "type": "<data type>"
       }
      ],
    "registrationType": "<endpoint type>"
   }
]

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.

[<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-exchange-us-1.goacoustic.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-exchange-us-1.goacoustic.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": <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": <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": <event catalog version>,
    "namespace": "<namespace>",
    "name": "<event name>",
    "description": "<text>",
    "attributes": 
      [  
       {
       "name": "<attribute name>",
       "type": "<data type>"
       }
      ],
    "registrationType": "<endpoint type>"
   }
]

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

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.

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

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.

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.

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

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.

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

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 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 Acoustic 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:///v1/eventfiles?numFiles=, where 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/

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

About this API

Call GET /v1/eventfiles/ as part of a series of calls to copy files from 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 Acoustic for your Acoustic Exchange account as the authorization bearer.

The base URL is the URL that Acoustic 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 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/ to remove the source event file after you retrieve all of the files.

DELETE /v1/eventfiles/

Call to Acoustic Exchange to remove a specific file from storage in Exchange.

About this API

After you finish copying an events file from Exchange you can call DELETE /v1/eventfiles/ 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/.

The base URL is the URL that Acoustic 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 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://exchange-us-1.goacoustic.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 /v1/subscription/notification to instruct Exchange to monitor subscriptions for a specified endpoint and report all changes immediately as an HTTP call.

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

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 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 Acoustic 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, Acoustic provides you with a Supplier key after you provide Acoustic 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" : "<Acoustic-provided key>", 
	  "refreshToken" : "<refresh token>"
	  }, 
   "notificationKey" :"<key value>", 
   "notificationURL" : "<URL for receiving notifications>"
}

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 Exchange user account. When you stop a subscription notification you are stopping notifications for a specific endpoint and Exchange user account. You must submit the authentication key that was provided by the Exchange user account to register the endpoint with Exchange.

Request

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