Application API/ Register endpoints

APIs that you call to register an endpoint that is based on an Exchange application. You register endpoints on behalf of Exchange users that request your endpoint in their Exchange working environment.

To call APIs that register an endpoint on behalf of an Exchange user, you must add the user-generated authentication key as the authorization bearer in the API call. The Acoustic Exchange user interface provides a way for users to generate the authentication key. You must provide a secure user interface or business practice to enable users to submit the key to you.

PUT /v1/endpoint/{applicationid}/{deploymentid}

About this API

Endpoints that are based on Exchange applications can support multiple features and accommodate deployment on multiple data centers. Registering endpoints as application-based endpoints greatly enhances your ability to respond to customer needs and changes in the features that you can offer.

When you register an endpoint that is based on an Exchange application you must specify the application ID and the deployment ID.

You must also be able to provide the authentication key that is generated by the Exchange user on whose behalf you are registering your endpoint. The user generates the authentication key in their Exchange interface. You provide the authentication key as the authorization bearer in the API request. Providing the user-generated authentication key verifies for Exchange that the Exchange user grants explicit permission for you to interact with Acoustic Exchange on the user’s behalf.

You must call this API separately for every Exchange user that requests your endpoint for use in their Exchange environment. You can call this API differently, depending on how you want to register the endpoint.

Register the endpoint and specify marketing database information that is different from what the Exchange application defines and includes features that define various event types.

Register the endpoint and include only features that define various event types. For example, register one endpoint that provides event data for email messaging and another for events related to SMS messaging.

Before you begin

Before you can register your endpoint as an endpoint provider on behalf of Exchange users, you must complete the following steps. Typically, you perform these steps in advance for each type of endpoint that you provide. You then call PUT v1/endpoint/{applicationid}/{deploymentid} each time that a different Exchange user requests that you register the endpoint.

Define an Exchange application on which the endpoint is based.
POST /v1/application

Add one or more features to the application.
POST /v1/application/{applicationID}/feature

For endpoints that publish event data, define the event types that the endpoint
supports.
POST /v1/application/{applicationID}/feature/{featureID}/eventtype

Define how Acoustic Exchange connects to the endpoint by defining the application deployments.
POST /v1/application/{applicationID}/deployment

Define how Acoustic Exchange users connect to the endpoint by defining user access.
PUT /v1/application/{applicationid}/deployment/{deploymentid}/onboarding

Request

You must specify the endpoint-level authentication key that a Acoustic Exchange user generates in the Acoustic Exchange user interface. As the endpoint provider, you are responsible for providing the means for the user to submit the authentication key to you in a secure manner.

The base URL for the API request is the URL that Acoustic assigned to your account during the initial account provisioning process.

The application ID is the value that Exchange generated when you created the application with the call to POST v1/application. The deploymentID is the value that you defined when you generated the feature by calling POST v1/application//deployment.

The following example illustrates a request (using curl) to register an endpoint that uses the global definitions for marketing database, audience attributes and identifiers, and does not define features. To register the endpoint only, make the call with an empty request body.

curl -v 
-X PUT 
-H "Authorization: Bearer <user-generated endpoint-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/endpoint/{applicationid}/{deploymentid}

Register endpoint – custom marketing database properties and list of features

The following example illustrates the format of a complete JSON for registering an endpoint with custom marketing database properties and a list of features that are available from the endpoint. The features define event types that the endpoint can provide.

Request JSON – custom marketing database and list of features

{ 
  "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>
            }
            ],
         "attributes": [
            {
            "name": "<attribute name>",
            "type": "<attribute type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>
            "isCaseSensitive": <true|false>
            },
         ]
      }
      ]
  },
  "features"  : [ "<feature name>","<feature name>" ]
}

Property	Use	Data type	Valid value	Description
marketingDatabases	Optional			The property definitions are the same as for PUT v1/ application. However, you can define the properties differently from the application-level properties, if necessary.
features	Optional	String	Valid Acoustic Exchange feature name.	List of features that are available from the endpoint.

Register endpoint – list of features only

The following example illustrates the format of a complete JSON for registering an endpoint that uses the application-level marketing database properties and specifies a list of features that are available from the endpoint. The features define event types that the endpoint can provide.

Request JSON – custom marketing database and list of features

{  
 {
  "features"  : [ "<feature name>","<feature name>" ]
  }
}

Register endpoint – endpoint only

The following example illustrates the format of a complete JSON for registering an endpoint only. To register the endpoint only, make the call with an empty request body.

Request JSON – custom marketing database and list of features

{ }

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.

PUT /v1/endpoint/application

About this API

When you register an endpoint using the PUT /v1/endpoint/application, Exchange retrieves the application ID and the deployment ID from the endpoint definition.

You must be able to provide the authentication key that is generated by the Acoustic Exchange user on whose behalf you are registering your endpoint. The user generates the authentication key in their Acoustic Exchange interface. You provide the authentication key as the authorization bearer in the API request. Providing the user-generated authentication key verifies for Acoustic Exchange that the Acoustic Exchange user grants explicit permission for you to interact with Acoustic Exchange on the user’s behalf.

Register the endpoint and specify marketing database information that is different from what the Exchange application defines and includes features that define various event types.
Register the endpoint and include only features that define various event types. For example, register one endpoint that provides event data for email messaging and another for events related to SMS messaging.
Register the endpoint only, without features or custom marketing database information.

Before you begin

Before you can register your endpoint as an endpoint provider on behalf of Exchange users, you must complete the following steps. Typically, you perform these steps in advance for each type of endpoint that you provide. You then call PUT v1/endpoint/application each time that a different Exchange user requests that you register the endpoint.

Define an Exchange application on which the endpoint is based.
POST /v1/application
Add one or more features to the application.
POST /v1/application/{applicationID}/feature
For endpoints that publish event data, define the event types that the endpoint supports.
POST /v1/application/{applicationID}/feature/{featureID}/eventtype
Define how Exchange connects to the endpoint by defining the application deployments.
POST /v1/application/{applicationID}/deployment
Define how Exchange users connect to the endpoint by defining user access.
PUT /v1/application/{applicationid}/deployment/{deploymentid}/onboarding

Request

You must specify the endpoint-level authentication key that an Exchange user generates in the Exchange user interface. As the endpoint provider, you are responsible for providing the means for the user to submit the authentication key to you in a secure manner.

The base URL for the API request is the URL that Acoustic assigned to your account during the initial account provisioning process.

curl -v 
-X PUT 
-H "Authorization: Bearer <user-generated endpoint-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/endpoint/application

Register endpoint – custom marketing database properties and list of features

The following example illustrates the format of a complete JSON payload for registering an endpoint with custom marketing database properties and a list of features that are available from the endpoint. The features define event types that the endpoint can provide.

Request JSON – custom marketing database and list of features

{ 
  "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>
            }
            ],
         "attributes": [
            {
            "name": "<attribute name>",
            "type": "<attribute type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>
            "isCaseSensitive": <true|false>
            },
         ]
      }
      ]
  },
  "features"  : [ "<feature name>","<feature name>" ]
}

Porperty	Use	Data type	Valid value	Description
marketingDatabases	Optional			The property definitions are the same as for PUT v1/ application. However, you can define the properties differently from the application-level properties, if necessary.
features	Optional	String	Valid Exchange	List of features that are available from the endpoint.

Register endpoint – list of features only

The following example illustrates the format of a complete JSON payload for registering an
endpoint that uses the application-level marketing database properties and specifies a list of
features that are available from the endpoint. The features define event types that the endpoint can
provide.

Request JSON – custom marketing database and list of features

{  
 {
  "features"  : [ "<feature name>","<feature name>" ]
  }
}

Register endpoint – endpoint only

The following example illustrates the format of a complete JSON payload for registering an endpoint only. To register the endpoint only, make the call with an empty request body.

Request JSON – custom marketing database and list of features

{ }

Response

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.

GET /v1/endpoint

Call GET /v1/endpoint with a user-generated endpoint-level authentication key to get a description of a specific endpoint that is registered with Exchange. The description can include various endpoint characteristics that you specify as additional query parameters in the API call.

About this API

When Exchange users register an endpoint, they generate an authentication key which is specific to the Exchange user account and the registered endpoint. Calls to Exchange APIs on behalf of a Exchange user account must include this authentication key as the authorization bearer for the call.

When you call GET /v1/endpoint with an endpoint authentication key, Exchange returns information that describes the single endpoint that is associated with the authentication key. In the URL for the call, you can include additional optional URL parameters to request specific endpoint characteristics. Separate parameters with &.

Request

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

The following example illustrates a request (using curl) to get information about an endpoint:

curl -v 
-X GET 
-H "Authorization: Bearer <user-generated endpoint-level authentication key>" 
https://<base URL>/v1/endpoint?<parameter 1>&<parameter 2>&<parameter n>

Note: the Authorization: Bearer must be an endpoint-level authentication key.

For example, calling the following URL returns descriptions for up to 20 segments that provide audience data from the endpoint that is associated with the endpoint-authentication key.

https:///v1/endpoint?segment=true&source=true&
loadSegments=true&startRecord=1&pageSize=20

Query parameter	Descripton
destination	Return descriptions of audience and event destination endpoints.Example: destination=true
event	Return descriptions of event source and event destination endpoints.Example:event=true
loadEvents	Use with event. Return the known eventTypes for an event producer.Example: event=true&loadEvents=true
loadSegments	Use with segment. Return the known segments for a segment producer.Example: segment=true&loadSegments=true
pageSize	Pass an integer value for the maximum number of segments to return in the call response. Use with segment.Example: segment=true&loadSegments=true& pageSize=10
searchByDescription	Pass a search criteria that might match a value in a segment description of a segment.Example: searchByDescription=opt-in.
searchByName	Pass a search criteria that might match the name of a segment.Example: searchByName=Recent opt-ins.
segment	Return descriptions of segment source and segment destination endpoints.Example:segment=true
source	Return descriptions of audience and event source endpoints.Example: source=true
startRecord	Use with pageSize. Pass an integer to start at a given record in the matching results.Example: pageSize=10&startRecord=2

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

DELETE /v1/endpoint

Delete a Acoustic Exchange endpoint for a specified Acoustic Exchange user account.

About this API

Call DELETE /v1/endpoint to remove the endpoint from the list of endpoints that appear as enabled and available to a specific Acoustic Exchange user account. In the API call, you must specify the authentication key that is associated with the Acoustic Exchange user.

Request

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

The following example illustrates a request (using curl) to remove endpoint information:

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

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.