To publish an event to Acoustic Exchange, make a POST request to the v1/event API. Acoustic Exchange provides several ways to use v1/event to publish events.

Acoustic Exchange supports two ways to publish events. You can publish events individually in a single POST to v1/event. You can also publish multiple events as a batch in a single API call.

Publishing events as a batch helps to avoid problems with the use and performance of your network resources. By publishing events in a batch, you can better manage high event volumes and more efficiently deliver events to Acoustic Exchange over an extended period.

Acoustic Exchange supports two ways to batch events, depending on the relationship of the events in the batch to each other. The difference between the batching methods determines how you build the JSON payload of the POST request to v1/event. When you publish a batch of events, consider how the events relate to each other, and make the following distinction.

• Simple batch. If the events in the batch are not related to each other in ways that establish dependencies, you can build the JSON payload as a simple set of separate event descriptions, including the identifiers for each event.
• Compound batch. If individual events in the batch are related by a common identifier, build the JSON payload as a list of identifiers and associate the related events under their common identifier. This relationship can occur when a single individual triggers multiple related events during the same interaction with your business solution. Cart events are a common example of such an interaction.

When you publish events in Acoustic Exchange, either individually or in a batch, the JSON payload contains the following properties.

• Channel The channel specifies where the event was observed. For example, specify mobile for events related to your mobile app.
• Identifiers The name and value of one or more identifiers that Acoustic Exchange can use to identify the specific individual who initiated the event. The identifier name must be registered with Acoustic Exchange for your endpoint.
• Timestamp The time when the event occurred, in ISO-8601 format.
• Event code Identifies a specific event that is recognized by Acoustic Exchange. The events that you specify must be registered with Acoustic Exchange for your endpoint. You must specify an event code that is defined by Acoustic Exchange.
• Event attributes Details that describe the event. The attributes must be registered with Acoustic Exchange for your endpoint.

You must specify identifiers that are registered with Exchange. To register an identifier, call POST v1/application or PUT v1/endpoint (for custom endpoints).

To describe an event, you must specify an event code and the event attributes that your business solution supports. You must register the event types and attributes with Acoustic Exchange for your endpoint. To register event types and attributes that you support, call POST v1/eventtype.

Publish individual events

To publish an individual event, make a POST call to the v1/event API. Specify a channel, one or more identifiers, and describe the event.

Publish events individually when you expect interactions with your business solution to occur in relatively low volumes and at random times. The mobile application installation event (application/installed) is an example of an event that happens occasionally and randomly. Individuals register your mobile app one at a time, and they can do so at any time.

You might also consider sending events individually if the event is time critical and any delay to accumulate multiple events might cause a problem. For example, it is likely that you want to publish opt-out requests as soon as possible. To publish an event individually, build the JSON payload in the POST request that defines the channel, an array of identifiers, and a single event description.

The diagram illustrates the general structure of the JSON payload that is required to publish individual events.

Acoustic Exchange originally introduced event publication as individual events as the only way to publish events. Although the v1/event API now supports sending events in a batch, event publishers do not need to change their existing implementation of v1/event. The v1/event API is fully compatible with existing implementations for sending individual events.

• Call POST <base URL>/v1/event.

See POST /v1/event for call details, including an example of how to build the JSON payload.