Acoustic Exchange provides a collection of public REST APIs that endpoints call to connect to Acoustic Exchange as producers and consumers of event and audience data. The APIs include various properties to provide customer identifiers and event attributes as part of the API call.

Acoustic Exchange endpoints call the Acoustic Exchange public APIs over SSL. Calls to Acoustic Exchange public APIs must contain a valid authentication key that Acoustic Exchange provides to Acoustic Exchange users for each endpoint that they register. 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.

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.

For a complete description of the Acoustic Exchange public APIs, see Acoustic Exchange public API reference.


Audience producer: PULL

Endpoints that allow Acoustic Exchange to pull audience data from the endpoint are considered a pull-type audience producer. To initiate the data exchange and related tasks, Acoustic Exchange calls APIs that are implemented by the endpoint.

Often, cloud-based business applications (also referred to as SaaS applications) connect to Acoustic Exchange as a pull-type audience producer.

The following table identifies the APIs that nay endpoint provider must implement to support actions that are expected of a pull-type audience producer.

Action by the endpoint Acoustic Exchange API calls

Provide a list of audiences (segments) that are available to provide audience data.

GET v1/segments
Provide details about a specific source audience. GET v1/segments/
{segmentId}
Upload available data to Acoustic Exchange. If no data is available, Acoustic Exchange requests that you create a data upload job. GET v1/segments/
{segmentId}/data
Create a job to upload audience data when it becomes available. POST v1/jobs
Provide job status. Acoustic Exchange polls for job status. It continues to poll when data upload begins and until the upload completes. GET v1/jobs/{jobId}
Upload the requested audience data. GET
v1/jobs/{jobId}/data/ {jobDataId}

Audience producer: PUSH

Endpoints that upload audience data and metadata to Acoustic Exchange are considered to be a push-type audience producer. To initiate the data upload and related tasks, the endpoint calls APIs that are hosted by Acoustic Exchange.

For example, to avoid potential security concerns, business applications that are physically installed in a local computer network as an On Premise application typically connect to Acoustic Exchange as a push-type endpoint.

The following table identifies the APIs that the endpoint must call to support actions that are expected of a push-type audience producer.

Action Acoustic Exchange API calls
Add a list to Acoustic Exchange that identifies segments that are ready for export to Acoustic Exchange. POST /v1/endpoint/{endpointId}/segments
Replace a list on Acoustic Exchange that identifies segments that are ready for export to Acoustic Exchange. PUT /v1/endpoint/{endpointId}/segments
Clear the list on Acoustic Exchange that identifies segments that are ready for export to Acoustic Exchange. DELETE /v1/endpoint/{endpointId}/segments
Remove a specific segment from the list on Acoustic Exchange that identifies segments that are ready for export to Acoustic Exchange. DELETE /v1/endpoint{endpointId}/segments/{segmentId}
Upload audience data and metadata to Acoustic Exchange in CSV format. POST /v1/jobs/{jobId}/data
Get a list of one or more jobs, identified by category, endpoint ID, or status. GET /v1/jobs/{jobCategory}
Get a specific job, identified by job category and job ID. GET /v1/jobs/{jobCategory}/{jobId}

Audience producer: PULL

Endpoints that allow Acoustic Exchange to pull audience data from the endpoint are considered a pull-type audience producer. To initiate the data exchange and related tasks, Acoustic Exchange calls APIs that are implemented by the endpoint.

Often, cloud-based business applications (also referred to as SaaS applications) connect to Acoustic Exchange as a pull-type audience producer.

The following table identifies the APIs that nay endpoint provider must implement to support actions that are expected of a pull-type audience producer.

Action by the endpoint Acoustic Exchange API calls

Provide a list of audiences (segments) that are available to provide audience data.

GET v1/segments
Provide details about a specific source audience. GET v1/segments/
{segmentId}
Upload available data to Acoustic Exchange. If no data is available, Acoustic Exchange requests that you create a data upload job. GET v1/segments/
{segmentId}/data
Create a job to upload audience data when it becomes available. POST v1/jobs
Provide job status. Acoustic Exchange polls for job status. It continues to poll when data upload begins and until the upload completes. GET v1/jobs/{jobId}
Upload the requested audience data. GET
v1/jobs/{jobId}/data/ {jobDataId}

Audience consumer: PUSH

Endpoints that allow Acoustic Exchange to push audience data to the endpoint are considered a push-type audience consumer. To initiate the data exchange and related tasks, Acoustic Exchange calls APIs that are implemented by the endpoint.

A push-type audience consumer is responsible for providing the means for Acoustic Exchange access and push the audience data and related metadata to the endpoint.

Often, cloud-based business applications (also called SaaS applications) connect to Acoustic Exchange as a push-type audience consumer.

The following table identifies the APIs that the consumer endpoint must implement to support actions that are expected of a push-type audience consumer.

Action by the endpoint Acoustic Exchange API calls

Provide a list of audiences that are already available as a destination audience and that can receive additional audience data or that can be modified by replacing or adding to existing data.

GET v1/segments
Provide details about a specific destination audience. GET v1/segments/
{segmentId}
Create an audience on the destination endpoint. POST v1/segments
Add audience data to the specified destination audience, either as a new audience or to existing audience. POST v1/segments/
{segmentId}/data?ids={ID}
Replace all existing data in the specified destination audience with new audience data. PUT v1/segments/
{segmentId}/data?ids={ID}
Delete specific records in the specified destination audience. DELETE
v1/segments/{segmentId}/data?ids={ID}

Audience consumer: PULL

Endpoints that download audience data and metadata from Acoustic Exchange are considered to be a pull-type audience producer. To initiate the data download and related tasks, the endpoint calls APIs that are hosted by Acoustic Exchange.

Business applications that are physically installed in a local computer network as an On Premise application typically connect to Acoustic Exchange as a pull-type endpoint.

The following table identifies the APIs that the endpoint must call to support actions that are expected of a pull-type audience consumer.

Action Acoustic Exchange API calls
Add a list to Acoustic Exchange that identifies segments that are ready for import to Acoustic Exchange. POST /v1/endpoint/{endpointId}/segments
Replace a list on Acoustic Exchange that identifies segments that are ready for import to Acoustic Exchange. PUT /v1/endpoint/{endpointId}/segments
Clear the list on Acoustic Exchange that identifies segments that are ready for import to Acoustic Exchange. DELETE /v1/endpoint/{endpointId}/segments
Remove a specific segment from the list on Acoustic Exchange that identifies segments that are ready for import to Acoustic Exchange. DELETE /v1/endpoint{endpointId}/segments/{segmentId}
Pull audience data files from Acoustic Exchange to a destination endpoint. GET /v1/jobs/{jobId}/segmentDataFiles/{fileName}
Clean up audience data files from Acoustic Exchange after downloading the data. DELETE/v1/jobs/{jobId}/segmentDataFiles/{fileName}
Mark an audience download job as complete and clean up files. PUT /v1/jobs/{jobid}/status/complete

Connection to Acoustic Exchange with account level access

To manage endpoints across an entire Acoustic Exchange user account, Acoustic Exchange provides APIs that can be called at the account level. The account level APIs require account level access credentials from Acoustic Exchange.

Action Acoustic Exchange API calls
Register specified endpoint with Acoustic Exchange. Requires account level authorization. PUT /v1/endpoint/{endpointId}
Delete a specific Acoustic Exchange endpoint. DELETE /v1/endpoint/{endpointId}
Get the details of a specified segment within a specified endpoint. GET /v1/endpoint/{endpointId}/segments/{segmentId}
Get a list of registered endpoints for an account, selected by various
characteristics.
GET /v1/endpoint
Start a job to export a specified segment from a specified source endpoint to a specified
destination endpoint.
POST /v1/jobs/segmentExport

Join The Discussion

Your email address will not be published. Required fields are marked *