Public APIs to connect producers and consumers

Acoustic Exchange provides a collection of public REST APIs that endpoints call to connect to 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. Exchange endpoints call the Exchange public APIs over SSL. Calls to Exchange public APIs must contain a valid authentication key that Exchange provides to Exchange users for each endpoint that they register. The authentication key identifies the Exchange endpoint and a specific Exchange user account that is associated with the endpoint.

All data exchanges through Exchange occur on behalf of a specific 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 Exchange account. Exchange does not share identifier data across Exchange accounts.

The authentication key must appear in the HTTP header of the API call. Exchange rejects any API call that does not specify an authentication key that Exchange can associate with a valid Exchange account.

Audience producer: PULL

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

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

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

Action by the endpoint	Acoustic Exchange
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 Exchange. If no data is available, 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. 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 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 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 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	Exchange API Calls
Add a list to Exchange that identifies segments that are ready for export to Exchange.	POST /v1/endpoint/{endpointId}/segments
Replace a list on Exchange that identifies segments that are ready for export to Exchange.	PUT /v1/endpoint/{endpointId}/segments
Clear the list on Exchange that identifies segments that are ready for export to Exchange.	DELETE /v1/endpoint/{endpointId}/segments
Remove a specific segment from the list on Exchange that identifies segments that are ready for export to Exchange.	DELETE /v1/endpoint{endpointId}/segments/{segmentId}
Upload audience data and metadata to 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

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

The following table identifies the APIs that the 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, 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. Exchange polls for job status. It continues to poll when data upload begins and until the upload completes.	GET v1/jobs/{jobId}
Uploaded the requested audience data.	GET v1/jobs/{jobId}/data/ {jobDataId}

Audience consumer: PUSH

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

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

Often, cloud-based business applications (also called SaaS applications) connect to 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 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 Exchange.

Business applications that are physically installed in a local computer network as an On Premise application typically connect to 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	Exchange API calls
Add a list to Exchange that identifies segments that are ready for import to Exchange.	POST /v1/endpoint/{endpointId}/segments
Replace a list on Exchange that identifies segments that are ready for import to Exchange.	PUT /v1/endpoint/{endpointId}/segments
Clear the list on Exchange that identifies segments that are ready for import to Exchange.	DELETE /v1/endpoint/{endpointId}/segments
Remove a specific segment from the list on Exchange that identifies segments that are ready for import to Exchange.	DELETE /v1/endpoint{endpointId}/segments/{segmentId}
Pull audience data files from Exchange to a destination endpoint.	GET /v1/jobs/{jobId}/segmentDataFiles/{fileName}
Clean up audience data files from 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 Exchange with account-level access

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

Action	Exchange API calls
Register specified endpoint with Exchange. Requires account level authorization.	PUT /v1/endpoint/{endpointId}
Delete a specific 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