Application API: Define applications

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.

Request JSON
{
  "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 IBM 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 estination (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.

Audience properties (excerpt from JSON)
     
      "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 REQURED, 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 <base URL>/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 IBM 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 IBM 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.

Join The Discussion

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