Acoustic Exchange makes various application programming interfaces (API) available to integrate business applications with . and Business Partner solutions call APIs to connect to , to provide descriptive information that appears in the 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 Exchange public APIs and it might add extra data to the response JSON. Any additional data will be in JSON format. If Exchange adds, changes, or removes required properties in an Exchange public API, it will create a new version of the API.
Exchange applications and authorized Acoustic Exchange Business Partners can call various REST APIs to establish and maintain a presence in Acoustic Exchange.
Call public APIs by submitting requests over SSL to the base URL that is provided by the provisioning team for your account. When creates your account, the Provisioning team provides your organization with access credentials and base URL for API calls to the 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 public APIs to the base URL that is assigned to your account.
Calls to public APIs must contain a valid authentication key that provides to users for each endpoint that they register. The authentication key must appear in the HTTP header of the API call. rejects any API call that does not specify an authentication key that can associate with a valid account.
The authentication key identifies the endpoint and a specific user account that is associated with the endpoint. All data exchanges through occur on behalf of a specific 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 account. does not share identifier data across accounts. To avoid SSL setup and teardown performance problems, your HTTP client must respect Keep-Alive headers returned by and reuse connections where possible.
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, 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. recommends that receiving endpoints ignore extra data in the API response and process only the data that the endpoint requires.
When business users want to add an endpoint their accounts, they generate an authentication key in the user interface. requires that the 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 generates when an user adds an endpoint. Each authentication key is unique to a single endpoint for a single user account. 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 user interface. Such a key is referred to as an endpoint-level authentication key. also makes account-level authentication keys available to applications and to Business Partners so that they can administer their endpoints in . never provides account-level authentication keys to users.
As an endpoint provider, if your organization makes multiple endpoints available in , your business systems must accommodate marketing users who might provide multiple endpoint authentication keys.