APIs to create and maintain Acoustic Exchange applications. Acoustic Exchange applications contain features that make it possible to register multiple endpoints that share a common set of properties and characteristics.

POST /v1/application

Create and define an Acoustic Exchange application.

About this API

In Acoustic Exchange, an application is a collection of metadata that describes an application or business solution that Acoustic Exchange users can select as an endpoint. As an endpoint provider, you define the application once and reference the application definition when you create new endpoint registrations in response to Acoustic Exchange user requests.

Request

Direct the API call to the base URL that is assigned to your Acoustic Exchange account.

When you call v1/application, you can omit JSON elements that do not apply to the type of application that you are creating. For example, when you create an application that provides audience data (a segment source), you can omit endpoint type properties for segment destination, event source, and event destination endpoint types.

The following example illustrates a request (using curl) to create an application that publishes events:

curl -v 
-X POST 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
-d ’{“providerName” : “<name of provider>”,"description" : "<endpoint description>",
“displayName” : “<name of endpoint>”,“hashAlgorithm” : “<default hashing method>”, 
"endpointTypes" : { "event" :{"source" : { "enabled" : true,"dataWindow" : <days>,
"sourceType" : "push" } } },
https://<base URL>/v1/application

The following table describes the complete JSON payload for the call.

{
  "providerName": "<endpoint provider name>",
  "description": "<endpoint description>",
  "displayName": "<endpoint name>",
  "hashAlgorithm": <algorithm type>,
  "endpointTypes": {
      "event": {
         "source": {
            "enabled": <true|false>,
            "dataWindow": <days>,
            "sourceType": "<push|pull>"
            },
         "destination": {
            "enabled": <true|false>,
            "destinationType": "<push|pull>"
            }
         }  
      "segment": {
         "source": {
            "enabled": <true|false>,
            "dataWindow": <days>,
            "sourceType": "<push|pull>"
            },
         "destination": {
            "enabled": <true|false>,
            "destinationType": "<push|pull>"
            "shareActions" : {                    
                "add": <true|false>,
                "remove": <true|false>,
                "replace": <true|false>
                "defaultShareAction":  <"ADD"|"REMOVE"|"REPLACE">
               }
            }
         },
      },
  "marketingDatabasesDefinition": {
      "marketingDatabases": [
         {
         "id": <string>,
         "name": "<source database name>",
         "identifiers": [
            {
            "name": "<identifier name>",
            "type": "<identifier type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>,
            "isCaseSensitive": <true|false>, 
            "isEventOnly": <true|false>
            }
            ],
         "attributes": [
            {
            "name": "<attribute name>",
            "type": "<attribute type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>,
            "isCaseSensitive": <true|false>
            },
         ]
      }
      ]
  }
}

Identify and describe the application

In the application definition, specify information that Acoustic Exchange requires to display and describe the business solution as an Acoustic Exchange endpoint in the Acoustic Exchange user interface. As required, you can specify a hashing algorithm to obscure potentially sensitive identity and attribute data.

Properties to describe the endpoint that is based on the Acoustic Exchange application (excerpt from JSON)

"providerName": "<endpoint provider name>",
  "description": "<endpoint description>",
  "displayName": "<endpoint name>",
  "hashAlgorithm": <algorithm type>,

Property	Use	Data type	Valid value	Description
providerName	Required	String	As defined by the business solution.	Name of the endpoint provider, typically your business name, as you want it to appear in the Acoustic Exchange user interface. Must be the provider name that you submitted to Acoustic Exchange when it provisioned your Acoustic Exchange account.
description	Optional	String	As defined by the business solution.	Description of the endpoint, as you want it to appear in the Acoustic Exchange user interface.
displayName	Required	String	As defined by the business solution.	Name of the endpoint, as you want it to appear in the Acoustic Exchange user interface. For example, a product name.
hashAlgorithm	Optional	String	MD5 SHA1 SHA256 EMAIL_SHA256 PHONE_SHA256	The hashing algorithm that Acoustic Exchange uses when destination endpoints require that Acoustic Exchange hash identity and attribute data. The algorithm that you specify here is a global definition that applies to all types of endpoints that you base on the application.

Enable event publishers and subscribers

In the application definition, you must specify if endpoints that are based on this application are an event source (publisher) or an event destination (subscriber). Use the event properties to enable endpoints that are based on the application.

Event properties (excerpt from JSON)

"event": {
         "source": {
            "enabled": <true|false>,
            "dataWindow": <days>,
            "sourceType": "<push|pull>"
            },
         "destination": {
            "enabled": <true|false>,
            "destinationType": "<push|pull>"
            }
         }

Property	Use	Data type	Valid value	Description
source	Required for event publishers	Not applicable	Not applicable	Enter values for source properties if the endpoint is an event publisher.
destination	Required for event subscribers	Not applicable	Not applicable	Enter values for destination properties if the endpoint is an event subscriber.
enabled	Required	Boolean	true \| false	Enable either source or destination.
dataWindow	Optional	Integer	Number of days	Typically used only when selecting and exchanging audience data.
sourceType	Required for event publishers	String	push pull	Push: allows the endpoint to push data to Acoustic Exchange. Pull: the endpoint prepares and stores event data for download and waits for Acoustic Exchange to retrieve the data.
destinationType	Required for event subscribers	String	push pull	Push: allows Acoustic Exchange to push event data to the endpoint. Pull: Acoustic Exchange prepares and stores event data for download and waits for the endpoint to retrieve the data.

Enable audience sources and destinations

In the application definition, you must specify if endpoints that are based on this application are audience sources (publishers) or an audience destinations (subscribers). Use the segment properties to enable endpoints that are based on the application.

"segment": {
         "source": {
            "enabled": <true|false>,
            "dataWindow": <days>,
            "sourceType": "<push|pull>"
            },
         "destination": {
            "enabled": <true|false>,
            "destinationType": "<push|pull>" 
            "shareActions" : {                    
                "add": <true|false>,
                "remove": <true|false>,
                "replace": <true|false>
                "defaultShareAction":  <"ADD"|"REMOVE"|"REPLACE">
               }
            }
         },

Property	Use	Data Type	Valid value	Description
source	Required for audience publishers	Not applicable	Not applicable	Enter values for source properties if the endpoint is an audience source.
destination	Required for audience consumers	Not applicable	Not applicable	Enter values for destination properties if the endpoint is an audience destination.
enabled	Required	Boolean	true \| false	Enable either source or destination.
dataWindow	Optional	Integer	Number of days	Acoustic Exchange users can specify a date range to limit how much data to upload to Acoustic Exchange. To restrict users to a specific number of days, specify the number of days that can be included in the date range, relative to the date that the export runs.
sourceType	Required for audience providers	String	push pull	Push: allows the endpoint to push data to Acoustic Exchange. Pull: the endpoint prepares and stores data for download and waits for Acoustic Exchange to retrieve the data.
destinationType	Required for audience subscribers	String	push pull	Push: allows Acoustic Exchange to push event data to the endpoint. Pull: Acoustic Exchange prepares and stores data for download and waits for the endpoint to retrieve the data.
shareActions	Required for audience subscribers	Not applicable	Not applicable	Options that define how audience providers are allowed to modify the destination database with new audience records.
add	Required	Not applicable	true \| false	Audience source is allowed to add records to the destination database.
remove	Optional	Not applicable	true \| false	Audience source is allowed to remove selected records from the destination database.
replace	Optional	Not applicable	true \| false	Audience source is allowed to remove records from the destination database and replace them with new records.
defaultShare Action	Required		ADD\|REMOVE\| REPLACE	Specify the default method for modifying the destination database. Acoustic Exchange allows ADD by default.

Source database for attributes and identifiers

Use properties in the marketing Databases Definition section to describe identifiers and attributes in event or audience data, including the source and schema of the source for identity lookup data.

You can use the marketing databases properties to describe the source and schema of the source for identity lookup data for events and audiences. Including these properties to identify the source database is optional. However, if you choose to identify the audience source, you must indicate the database name.

Marketing database properties (excerpt from JSON)

"marketingDatabasesDefinition": {
      "marketingDatabases": [
         {
         "id": <string>,
         "name": "<source database name>",
         
         //"identifiers" and "attributes" sections are removed in this example
      }
      ]
  }

Property	Use	Data type	Valid value	Description
id	Optional	String	As defined in your business systems.	Identifier for the source database, as applicable.
name	Required if you identify the audience database.	String	As defined in your business systems	Name of the database that provides the audience data.

Audience identifiers and attributes

Use the marketing databases definition properties to describe identifiers and
attributes in event or audience data, including the source and schema of the source for identity lookup data. Specifying a database name is optional.

Acoustic Exchange uses identifier attributes to identify specific individuals in an audience. Over time, Acoustic Exchange merges identity records of the same type for the same individual to provide a detailed view of the customer in multiple contexts. You can define one or more attributes that relate to a specific individual.

You must specify the name of the identifier and type of data that the identifier provides. To support augmenting audience identities, the type of identifier in the audience source must match the type of identifier in the destination. The names might be different, but the types must be same.

You can define or more attributes that describe at least some of the individuals that are present in an audience.

Audience identifiers and attributes (excerpt from JSON)

"identifiers": [
            {
            "name": "<identifier name>",
            "type": "<identifier type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <hash algorithm type>,
            "isRequired": <true|false>,
            "isCaseSensitive": <true|false>,
            "isEventOnly": <true|false>
            }
            ],
         "attributes": [
            {
            "name": "<attribute name>",
            "type": "<attribute type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>,
            "isCaseSensitive": <true|false>
            }
         ]

Property	Use	Data type	Valid value	Description
name	Required	String	As defined in your business systems	Name of the identifier or attribute as provided by the source endpoint.
type	Required	Identity type	As defined in your business systems	Indicate the type of identifier. If possible, match the type to an Acoustic Exchange identity key. The type that is specified in the audience source must match the type that is specified in the audience destination.
hashMode	Optional	String	NONE HASHED REQUIRED	If the endpoint requires obscuring identifiers or attributes, specify how to hash the values, as follows. None: No hashing is required. (Can be null.) Hashed: The audience provider hashes the value, by using the algorithm that is specified in the hashAlgorithm property. Required: Acoustic Exchange must hash the value that is sent to the audience destination. If the destination endpoint does not specify an algorithm, use the default algorithm.
hashAlgorithm	Optional	String	MD5 SHA1 SHA256 EMAIL_SHA256 PHONE_SHA256	If the hashMode is REQUIRED, then this property specifies the algorithm that the audience source endpoint uses to hash the identifier or attribute.
isRequired	Required	Boolean	true \| false	Indicates whether the source endpoint must specify the identifier or attribute.
isCaseSensitive	Optional	Boolean	true \| false	Instructs Acoustic Exchange to convert upper case or mixed case identifier values to lower case so that Acoustic Exchange can join the identifiers. Acoustic Exchange matches lower case values only. By default, this field is null, which Acoustic Exchange treats as true (case-sensitive). If false, Acoustic Exchange converts the identifier values to lower case and joins identifiers with matching values. Acoustic Exchange evaluates and converts values for identifiers. It does not evaluate values for attributes.
isEventOnly	Optional	Boolean	true \| false	Indicates whether the identifier applies only to event data. By default, this property is false, which means the identifier can appear in event and audience data. If true, the identifier cannot be used to identify audience members. Can be null. Note: Do not apply to attributes. For identifiers only.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

For a successful call, the response includes a JSON payload that matches the payload of the request but also includes a new, system-generated property: "id" : "{application id}.

For example, the returned JSON includes the new application ID, as illustrated here.

Returned JSON (partial)

"id":<applicationID>,
  "providerName": "<endpoint provider name>",
  "description": "<endpoint description>",
  "displayName": "<endpoint name>",
  "hashAlgorithm": <algorithm type>,

  //Remainder of the returned JSON payload is not shown in this example.

Acoustic Exchange uses the value of this new property to identify the application that the API call creates.

Record the value for "id" because you must specify it in other application API calls.

PUT /v1/application/{applicationid}

Update the definition of an Acoustic Exchange application.

About this API

Call PUT /v1/application/{application Id} to make changes to the definition of an Acoustic Exchange application. For example, as you are implementing your business solution with Acoustic Exchange, you can call this API to make adjustments.

Request

You must specify the account-level authentication key that Acoustic provided for your Acoustic Exchange account.

The application ID is the value that Acoustic Exchange generated when you created the application with the call to POST v1/application.

The structure of the JSON payload for the PUT call is identical to the payload structure for the POST call. Update the values that you want to change.

The following example illustrates a request (using curl) to update an application that publishes events:

curl -v 
-X PUT 
-H "Authorization: Bearer <application-level authentication key>" 
-H "Content-Type: application/json" 
-d ’{"id":<applicationID>,“providerName” : “<name of provider>”,
"description" : "<endpoint description>",“displayName” : “<name of endpoint>”,
“hashAlgorithm” : “<NEW hashing method>”,"endpointTypes" : 
{ "event" :{"source" : { "enabled" : true,"sourceType" : "push" } } },
https://<base URL>/v1/application/<applicationID>

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

A successful call response includes a JSON payload that contains the updated values. The value for applicationID does not change.

GET /v1/application

Request details for all applications that are associated with a specific account-level authentication key.

About this API

This API returns details for all applications that are associated with the account authentication key that was specified when the application was created with a call to POST v1/application. The response includes application details as JSON for each application, including the application ID for each application.

For example, you might call GET v1/application if you forget the application ID for an application.

Request

You must specify the account authentication key that you received from Acoustic Exchange for your account as the authorization bearer.

The base URL is the URL that Acoustic Exchange assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to retrieve details for applications that were created with the specified authentication key:

curl -v 
-X GET 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

A successful response includes JSON payloads for each Acoustic Exchange application that was created with the account authentication key that you specified as the authorization bearer in the GET call.

The returned JSON matches the payload that was used to create each application with a call to POST v1/application.

GET /v1/application/{applicationid}

Retrieve information about an existing Acoustic Exchange application.

About this API

Call this API to get details for a specific Acoustic Exchange application.

Request

You must specify the application ID that Acoustic Exchange generates when you called POST v1/application to create the application. You must also specify the account authentication key that you received from Acoustic for your Acoustic Exchange account.

The base URL is the URL that Acoustic Exchange assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to retrieve details for applications that were created with the specified authentication key:

curl -v 
-X GET 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

A successful response includes a JSON payload that describes the specified application. The JSON matches the payload that was used in the POST v1/application call to create the application.

PUT /v1/application/{applicationid}/{status}

Update the visibility status of an Acoustic Exchange application.

About this API

Use this API to change the status of an Acoustic Exchange application. The status of an Acoustic Exchange application can be either PUBLIC or PRIVATE.

PUBLIC: the application is visible to all accounts in the Acoustic Exchange pilot environment.
PRIVATE: the application is visible only to authorized users in the Acoustic Exchange account in which the application was created.
##Request
You must specify the account-level authentication key that Acoustic Exchange provided for your account.

The application ID is the value that Acoustic Exchange generated when you created the application with the call to POST v1/application.

The base URL is the URL that Acoustic Exchange assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to change the visibility status of a specified Acoustic Exchange application:

curl -v 
-X PUT 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>/{status}

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

For a successful call, the response returns a success code and the new status. For example, to restrict the visibility an application that is currently visible to all users in the Acoustic Exchange Pilot environment, a successful call to PUT v1/application/<applicationID/{status} returns:

200 OK, "PRIVATE"
##GET /v1/application/{applicationid}/{status}
Determine the visibility status of an Acoustic Exchange application.

About this API

Use this API to determine the status of an Acoustic Exchange application.

The status of an Acoustic Exchange application can be either PUBLIC or
PRIVATE.

PUBLIC: the application is visible to all accounts in the Acoustic Exchange pilot environment.
PRIVATE: the application is visible only to authorized users in the Acoustic Exchange account in which the application was created.
Request
You must specify the account-level authentication key that Acoustic Exchange provided for your account.

The application ID is the value that Acoustic Exchange generated when you created the application with the call to POST v1/application.

The base URL is the URL that Acoustic Exchange assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to change the visibility status of a specified Acoustic Exchange application:

curl -v 
-X GET 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>/{status}

Response

Acoutic Exchange public APIs return standard HTTP 1.1 response codes.

For a successful call, the response returns a success code and the new status. For example, to determine who can see the specified application, a successful call to PUT v1/application/<applicationID/{status} might indicate that it is currently visible to all users in the Acoustic Exchange Pilot environment, as follows:

200 OK, "PUBLIC"
##DELETE /v1/application/{applicationid}
To delete an Acoustic Exchange application.

About this API

Use this API to remove the specified Acoustic Exchange application.

Request

You must specify the account-level authentication key that Acoustic Exchange provided for your account.

The application ID is the value that Acoustic Exchange generated when you created the application with the call to POST v1/application.

The base URL is the URL that Acoustic Exchange assigned to your account during the initial account provisioning process. Make the call with an empty request body.

The following example illustrates a request (using curl) to remove the specified Acoustic Exchange application:

curl -v 
-X DELETE 
-H "Authorization: Bearer <account-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/application/<applicationID>

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

The call returns a 400 error if Acoustic Exchange detects an endpoint that references the application ID.