Acoustic Exchange makes various application programming interfaces (API) available to integrate business applications with Acoustic Exchange. Acoustic Exchange and Acoustic Exchange Business Partner solutions call Acoustic Exchange APIs to connect to Acoustic Exchange, to provide descriptive information that appears in the Acoustic Exchange user interface, and to manage the exchange of event and audience data between separate business applications.

Acoustic Exchange reserves the right to add optional properties to the current version of the Acoustic Exchange public APIs and it might add extra data to the response JSON. Any additional data will be in JSON format. If Acoustic Exchange adds, changes, or removes required properties in an Acoustic Exchange public API, it will create a new version of the API.

Acoustic Exchange API overview

Acoustic Exchange applications and authorized Acoustic Exchange Business Partners can call various REST APIs to establish and maintain a presence in Acoustic Exchange.

Acoustic Exchange provides the following types of APIs.

Application-level APIs

Account-level APIs:

Account-level API

Endpoint-level APIs:

Endpoint API/Custom Endpoints

Event APIs:

Event API

Jobs APIs:

Jobs API

Identity management APIs:

Identity management APIs

Segment API

Segment API

Requests to Acoustic Exchange public APIs

Call Acoustic Exchange public APIs by submitting requests over SSL to the base URL that is provided by the Acoustic Exchange provisioning team for your account. When Acoustic Exchange creates your account, the Acoustic Exchange Provisioning team provides your organization with access credentials and base URL for API calls to the Acoustic Exchange Pilot environment. When your account moves to the Production environment, the Provisioning team updates the base URL to point to Production. Direct all calls to the Acoustic Exchange public APIs to the base URL that is assigned to your Acoustic Exchange account.

Calls to Acoustic Exchange public APIs must contain a valid authentication key that Acoustic Exchange provides to users for each endpoint that they register. The authentication key must appear in the HTTP header of the API call. Acoustic Exchange rejects any API call that does not specify an authentication key that Acoustic Exchange can associate with a valid Acoustic Exchange account.

The authentication key identifies the Acoustic Exchange endpoint and a specific Acoustic Exchange user account that is associated with the endpoint. All data exchanges through Acoustic Exchange occur on behalf of a specific Acoustic Exchange user and user account. Including an authentication key with each API call ensures that the data is directed to the correct destination and that customer identifiers are attributed to the correct Acoustic Exchange account. Acoustic Exchange does not share identifier data across Acoustic Exchange accounts. To avoid SSL setup and teardown performance problems, your HTTP client must respect Keep-Alive headers returned by Acoustic Exchange and reuse connections where possible.

Responses from Acoustic Exchange public APIs

Acoustic Exchange public APIs return standard HTTP 1.1 response codes to describe the success or failure of the call. Some responses include a JSON payload.
Typically, Acoustic Exchange public APIs return responses as follows.

200 to 299: Success.
400-499: There is a problem with the API request. Examine the request for errors.
500-599: System error. Contact Support for assistance.

Depending on the API method, the response can include a JSON payload. The APIs include various properties to provide customer identifiers and event attributes as part of the API call. In some cases, depending on the needs of the data destination endpoint, the response JSON might provide data that is not required by the receiving endpoint. Acoustic Exchange recommends that receiving endpoints ignore extra data in the API response and process only the data that the endpoint requires.

Authentication key submission by Acoustic Exchange users

When business users want to add an endpoint their Acoustic Exchange accounts, they generate an authentication key in the Acoustic Exchange user interface. Acoustic Exchange requires that the Acoustic Exchange user submit the authentication key to the endpoint. You must create a method to accept the authentication key.

The authentication key is a 16-digit alphanumeric string that Acoustic Exchange generates when an Acoustic Exchange user adds an endpoint. Each authentication key is unique to a single endpoint for a single Acoustic Exchange user account. Acoustic Exchange users are required to create a new authentication key for each endpoint.

API calls to perform an action on behalf of a specific user account must provide the authentication key that the user generated in the Acoustic Exchange user interface. Such a key is referred to as an endpoint-level authentication key. Acoustic Exchange also makes account-level authentication keys available to Acoustic Exchange applications and to Acoustic Exchange Business Partners so that they can administer their endpoints in Acoustic Exchange. Acoustic Exchange never provides account-level authentication keys to Acoustic Exchange users.

As an endpoint provider, if your organization makes multiple endpoints available in Acoustic Exchange, your business systems must accommodate Acoustic Exchange marketing users who might provide multiple endpoint authentication keys.