Public APIs to connect producers and consumers
Acoustic Exchange provides a collection of public REST APIs that endpoints call to connect to {user.ex-short} 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. {user.ex-short} endpoints call the {user.ex-short} public APIs over SSL. Calls to {user.ex-short} public APIs must contain a valid authentication key that {user.ex-short} provides to {user.ex-short} users for each endpoint that they register. The authentication key identifies the {user.ex-short} endpoint and a specific {user.ex-short} user account that is associated with the endpoint.
All data exchanges through {user.ex-short} occur on behalf of a specific {user.ex-short} 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 {user.ex-short} account. {user.ex-short} does not share identifier data across {user.ex-short} accounts.
The authentication key must appear in the HTTP header of the API call. {user.ex-short} rejects any API call that does not specify an authentication key that {user.ex-short} can associate with a valid {user.ex-short} account.
Audience producer: PULL
Endpoints that allow {user.ex-short} to pull audience data from the endpoint are considered a pull-type audience producer. To initiate the data exchange and related tasks, {user.ex-short} calls APIs that are implemented by the endpoint.
Often, cloud-based business applications (also referred to as SaaS applications) connect to {user.ex-short} 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 {user.ex-short}. If no data is available, {user.ex-short} 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. {user.ex-short} 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 {user.ex-short} 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 {user.ex-short}.
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 {user.ex-short} 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 | {user.ex-short} API Calls |
|---|---|
| Add a list to {user.ex-short} that identifies segments that are ready for export to {user.ex-short}. | POST /v1/endpoint/{endpointId}/segments |
| Replace a list on {user.ex-short} that identifies segments that are ready for export to {user.ex-short}. | PUT /v1/endpoint/{endpointId}/segments |
| Clear the list on {user.ex-short} that identifies segments that are ready for export to {user.ex-short}. | DELETE /v1/endpoint/{endpointId}/segments |
| Remove a specific segment from the list on {user.ex-short} that identifies segments that are ready for export to {user.ex-short}. | DELETE /v1/endpoint{endpointId}/segments/{segmentId} |
| Upload audience data and metadata to {user.ex-short} 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 {user.ex-short} to pull audience data from the endpoint are considered a pull-type audience producer. To initiate the data exchange and related tasks, {user.ex-short} calls APIs that are implemented by the endpoint.
Often, cloud-based business applications (also referred to as SaaS applications) connect to {user.ex-short} 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, {user.ex-short} 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. {user.ex-short} 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 {user.ex-short} to push audience data to the endpoint are considered a push-type audience consumer. To initiate the data exchange and related tasks, {user.ex-short} calls APIs that are implemented by the endpoint.
A push-type audience consumer is responsible for providing the means for {user.ex-short} access and push the audience data and related metadata to the endpoint.
Often, cloud-based business applications (also called SaaS applications) connect to {user.ex-short} 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 {user.ex-short} 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 {user.ex-short}.
Business applications that are physically installed in a local computer network as an On Premise application typically connect to {user.ex-short} 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 {user.ex-short} that identifies segments that are ready for import to {user.ex-short}. | POST /v1/endpoint/{endpointId}/segments |
| Replace a list on {user.ex-short} that identifies segments that are ready for import to {user.ex-short}. | PUT /v1/endpoint/{endpointId}/segments |
| Clear the list on {user.ex-short} that identifies segments that are ready for import to {user.ex-short}. | DELETE /v1/endpoint/{endpointId}/segments |
| Remove a specific segment from the list on {user.ex-short} that identifies segments that are ready for import to {user.ex-short}. | DELETE /v1/endpoint{endpointId}/segments/{segmentId} |
| Pull audience data files from {user.ex-short} to a destination endpoint. | GET /v1/jobs/{jobId}/segmentDataFiles/{fileName} |
| Clean up audience data files from {user.ex-short} 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 {user.ex-short} user account, {user.ex-short} provides APIs that can be called at the account level. The account level APIs require account-level access credentials from {user.ex-short}.
| Action | Exchange API calls |
|---|---|
| Register specified endpoint with {user.ex-short}. Requires account level authorization. | PUT /v1/endpoint/{endpointId} |
| Delete a specific {user.ex-short} 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 |
Updated 17 days ago