Endpoint API/ Custom endpoints

APIs to individually register and manage Acoustic Exchange endpoints for Exchange user accounts. Call these APIs if you do not create Exchange applications to collectively define and enable multiple endpoints that are based on features defined for an Exchange application.

PUT /v1/endpoint

Register an endpoint with Acoustic Exchange.

Before you begin

You register an endpoint with Exchange at the explicit request of a business user who wants to use Exchange to exchange data between applications.

Business users that want to use your application with Exchange must give you an authentication key that they generate in the Exchange user interface. You must include the authentication key as the authorization bearer in the call to the v1/endpoint API. The authentication key indicates to Exchange that the Exchange user grants permission for the endpoint to interact with Exchange on behalf of the Exchange user.

As an Exchange endpoint provider, you are responsible for describing and providing Acoustic Exchange business users with a method to submit the authentication key that they generate in Exchange.

Confirm that you received an authentication key from the Exchange user before you call v1/endpoint.

About this API

Call v1/endpoint to register an Acoustic application, or approved Acoustic Exchange Business Partner application, as a custom endpoint in Exchange on behalf of a registered Exchange user.

You can register an application as any of the following endpoint types.

• Source of events – an event publisher
• Destination for events – an event subscriber
• Source of audience data – an audience producer
• Destination for audience data – an audience consumer

In the call to v1/endpoint, you provide the following types of information.

• Properties to identify and describe the endpoint. Exchange uses the information to present the endpoint in the Exchange user interface.
• Hashing algorithms to obscure sensitive personal data.
• Endpoint types. You can create multiple endpoint types in a single API call.
• Name and type of identifiers that can be used to identify individuals who are represented in event and audience data.
• Name and type of attributes that describe individuals who are represented
  in audience data.

In the call, you explicitly enable the endpoint as a specific endpoint type. The type of endpoint determines the properties that you set in the call.

When you call v1/endpoint, you can omit JSON elements that do not apply to the type of endpoint that you are registering. For example, when you register an endpoint that provides audience data (a segment producer), you can omit endpoint type properties for audience destination and event publisher and subscriber endpoints.

You can disable the endpoint for specific users by removing the endpoint type enablement in a subsequent call to v1/endpoint with the appropriate authentication key for the user.

Request

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

Example requests (as curl commands):

To register endpoints that publish or subscribe to events:

Event publisher and subscriber endpoints (curl)
curl -v 
  -X PUT 
  -H "Authorization: Bearer <1234-abcd-5678-efgh>" 
  -H "Content-Type: application/json" 
  -d '{“providerName” : “<name of provider>”,“name” : “<name of endpoint>”,
     “description” : “<description>”, "endpointTypes" : { "event" : 
     {"<source | destination>" : {  "enabled" : true,  
     "destinationType" : "<push | pull>" }  } }, 
     “url” : “<URL for endpoint>”}' 
     <base URL>/v1/endpoint

To register endpoints that provide or consume audience data:

curl -v 
    -X PUT 
    -H "Authorization: Bearer <1234-abcd-5678-efgh>" 
    -H "Content-Type: application/json" 
    -d '{“providerName” : “<name of provider>”,“name” : “<name of endpoint>”,
       “description” : “<description>”, "endpointTypes" : { "segment" : 
       {"<source | destination>" : {  "enabled" : true,  
       "destinationType" : "<push | pull>" }  } }, 
       “url” : “<URL for endpoint>”}' 
    <base URL>/v1/endpoint

The following table describes the JSON payload of the call.

A: Identify and describe the endpoint

Provide information that Exchange requires to identify the endpoint and display it in the Exchange user interface.

Specify a URL that Exchange uses to contact the endpoint and to which it posts event and audience data. When you define an endpoint type, you can define a different URL that takes precedence over the global URL.

As required, you can specify a hashing algorithm to obscure potentially sensitive identity and attribute data.

B: Enable event publishers and subscribers

To register endpoints that publish or subscribe to event data, you must enable each endpoint separately as either an event source or an event destination.

C: Enable audience sources and destinations

To register endpoints that syndicate audience data, you must enable each endpoint separately as either a segment source or a segment destination.

D: Identify an audience database

Under marketing Databases Definition, describe the source and schema of the source for identity lookup data for events and audiences.

Specifying a database name is optional.

E: Specify contact identifiers

Acoustic Exchange uses identifier attributes to identify specific individuals in an audience. Over time, 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.

F: Specify audience attributes

Not applicable to register endpoints that publish or subscribe to events. Optional for audience sources and destinations.

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

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

PUT v1/endpoint provides responses as follows.

What to do next

If the endpoint that you register requires authenticated login, call the v1/endpointattributes API to provide Acoustic Exchange with the connection and authentication information that it requires to automatically connect with the endpoint.

PUT /v1/endpointattributes

Call the v1/endpointattributes API to provide Acoustic Exchange with authentication credentials and connection information that Acoustic Exchange can use to construct secure, automatic connections to endpoints.

Before you begin

Register the endpoint that you want to access with Acoustic Exchange. Use the /v1/endpoint API to register the endpoint with Acoustic Exchange.

Acoustic Exchange retrieves the information that you provide in calls to v1/endpointattributes nightly. As a result, Acoustic Exchange cannot construct an automated connection to an endpoint immediately after you call v1/endpoint. You must wait until the following day to verify that Acoustic Exchange can automatically construct a secure connection to the endpoint.

About this API

If an endpoint requires authenticated access, the endpoint can call the v1/endpointattributes API to provide Acoustic Exchange with login credentials and connection information. No human intervention is required.

v1/endpointattributes provides connection and login information as attributes in the JSON payload of the API call. The specific attribute names and values depend on the access methods and requirements of the endpoint.

Calling v1/endpointattributes more than once overwrites information that was provided by the previous call.

Request

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

The call accepts an authentication key as a URL parameter. Enter the authentication key that was used to register the endpoint for which you are configuring access. The authentication key is unique to the endpoint and the specific Acoustic Exchange account that requested that the endpoint registration. The authentication key is required as a URL parameter and as the authorization bearer in the header of the call.

To specify the user account, provide the authentication key for the account as the authorization bearer in the API call.

Example request (as a curl command):

-X POST 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -H "Content-Type: application/json" 
  -d '{“name” : “<access attribute>”,“name2” : “<access attribute2>”}' 
  <base URL>/v1/endpointattributes/authkey/"1234-abcd-5678-efgh"

The following table describes the JSON payload of the call.

A: Enter connection and authentication attributes

You can enter multiple name and value pairs in the API call.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

PUT /v1/endpointattributes/authkey/"" provides responses as follows.

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 an 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 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

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

DELETE /v1/endpoint

Delete an Exchange endpoint for a specified 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 Exchange user account. In the API call, you must specify the authentication key that is associated with the Exchange user.

Request

Direct the API call to the base URL that is assigned to your 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.

POST /v1/endpoint/{endpointId}/segments

As a push type audience producer, endpoints call this API to identify and describe one or
more audiences that are ready for export to Exchange.

About this API

Endpoints that make this API call must be registered with Exchange as a push producer type.

To call this API, you must be able to provide the endpoint ID for your endpoint.

Provide the following information in the call to this API:

• Authentication key that is associated with an Acoustic Exchange user account for which you are making the audience data available
• Endpoint ID for the endpoint that provides the segment (audience data), submitted as a URL parameter
• Segment ID for each segment
• Name for each segment
• Segment type
• Attributes for each segment
  ###Request
  Direct the API call to the base URL that is assigned to your Exchange account.

Request format (as a curl command):

curl -v
-X POST 
-H "Authorization: Bearer <endpoint authentication key>" 
-H "Content-Type: application/json" 
-d ’[
     {
      "id":"<segment ID>",
      "name":"<segment name>",
      "description": "<segment description>",
      "type":"<segment type>",
      "segment_attributes": 
       [
        {
         "name": "<attribute name>",
         "type": "<data type>"
         },
         {
          "name": "<attribute name>",
          "type": "<data type>"
          },
         {
          "name": "<attribute name>",
          "type": "<data type>"
          }
        ]
       },
      {
       "id":"<segment ID>",
       "name":"<segment name>",
       "description": "<segment description>",
       "type": "<segment type>",
       "segment_attributes": 
        [
         {
          "name": "<attribute name>",
          "type": "<data type>"
         },
         {
          "name": "<attribute name>",
          "type": "<data type>"
          }
         ]
        }
      ] ’ 

<base URL>/v1/endpoint/<endpointID>/segments

The following table describes the JSON payload of the call.

If the audience segment has a string segment ID, then the property id_string
should be defined in place of the property id. A segment with a string ID might
look like the following example.

[
  {
   "id_string":"<first segment ID>",
   "name":"<first segment (audience) name>",
   "description":"<first audience description>"
  },
  {
   "id_string":"<second segment ID>", 
   "name":"<second segment (audience) name>", 
   "description":"<second audience description>"
  }
]

Available audiences

You can upload multiple audiences in a single call.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

POST /v1/endpoint/{endpointId}/segments provides responses as follows.

PUT /v1/endpoint/{endpointId}/segments

As a push type audience producer, call this API to replace data that describes one or more audiences that are ready for export to Acoustic Exchange.

About this API

Endpoints that make this API call must be registered with Acoustic Exchange as a push producer type.

To call this API, you must be able to provide the endpoint ID for your endpoint.

Provide the following information in the call to this API:

• Authentication key that is associated with a Acoustic Exchange user account for which you are making the audience data available
• Endpoint ID for the endpoint that provides the segment (audience data), submitted as a URL parameter
• Segment ID for each segment
• Segment type
• Name for each segment
• Attributes for each segment
  ###Request
  Direct the API call to the base URL that is assigned to your Acoustic Exchange account.

Request format (as a curl command):

curl -v
-X PUT 
-H "Authorization: Bearer <endpoint authentication key>" 
-H "Content-Type: application/json" 
-d ’[
     {
      "id":<segment ID>,"name":"<segment name>",
      "description":"<segment description>",
      "type":"<segment type>",
      "segment_attributes":
       [
        {
         "name": "<attribute name>",
         "type": "<data type>"
         },
        {   
         "name":"<attribute name>",
         "type": "<data type>"
         },
        {  
         "name": "<attribute name>",
         "type":"<data type>"
         }
        ]
       },
       {
        "id":<segment ID>,
        "name":"<segment name>",
        "description":"<segment description>",
        "type":"<segment type>",
        "segment_attributes":
         [
          {
           "name":"<attribute name>",
           "type": "<data type>"
           },
           {"name": "<attribute name>",
            "type": "<data type>"
           }
         ]
        }
      ] ’ 
<base URL>/v1/endpoint/<endpointID>/segments

The following table describes the JSON payload of the call.

If the audience segment has a string segment ID, then the property id_string should be defined in place of the property id. A segment with a string ID might look like the following example.

[
  {
   "id_string":"<first segment ID>",
   "name":"<first segment (audience) name>",
   "description":"<first audience description>"
  },
  {
   "id_string":"<second segment ID>", 
   "name":"<second segment (audience) name>", 
   "description":"<second audience description>"
  }
]

Available segments

You can update multiple segments in a single call.

Response

Exchange public APIs return standard HTTP 1.1 response codes.

PUT /v1/endpoint/{endpointId}/segments provides responses as follows.

DELETE /v1/endpoint/{endpointId}/segments

Clear the list on Acoustic Exchange that identifies segments that are ready for export or import to Exchange.

About this API

Endpoints that provide audience data make this call to Acoustic Exchange to empty the list of segments on the endpoint that are available for upload to Exchange.

Endpoints that make this API call must be registered with Exchange as a push producer type.

To call this API, you must provide the endpoint ID for the endpoint that provided the segment (audience data) that was uploaded to Exchange. You must also provide the authentication key that is associated with an Exchange user account.

Request

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

Example request (as a curl command):

curl -v

-X DELETE 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -H "Content-Type: application/json" 
  <base URL>/v1/endpoint/<endpointID>/segments

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

DELETE /v1/endpoint/{endpointId}/segments provides responses as follows.

DELETE /v1/endpoint/{endpointId}/segments/{segmentId}

Remove a specific segment from the list on Exchange that identifies segments that are ready for export or import to Exchange.

About this API

Endpoints that provide audience data make this call to Exchange to remove a single segment from the list of segments on the endpoint that are available for upload to Exchange.

Endpoints that make this API call must be registered with Exchange as a push producer type.

To call this API, you must provide the segment ID for the segment (audience data) that you want to remove and the endpoint ID for the endpoint that provided the segment. You must also provide the authentication key that is associated with an Exchange user account.

Request

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

Example request (as a curl command):

curl -v

-X DELETE 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -H "Content-Type: application/json" 
  <base URL>/v1/endpoint/<endpointID>/segments/{<segmentID>}

Response

Exchange public APIs return standard HTTP 1.1 response codes.

DELETE /v1/endpoint/{endpointId}/segments/ provides responses as follows.

PUT /v1/endpoint/enable

Call this API to enable an endpoint that has been registered on behalf of a Acoustic Exchange user account.

Before you begin

Register the endpoint using PUT v1/endpoint.

About this API

When you call PUT /v1/endpoint/enable, Acoustic Exchange enables the endpoint that is associated with the authentication key that you include as the authorization bearer in the API call.

Request

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

Request format (as a CURL command)

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

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

PUT v1/endpoint/enable provides responses as follows.

PUT /v1/endpoint/disable

Call this API to disable an endpoint that has been registered on behalf of an Exchange user account.

Before you begin

Register the endpoint using PUT v1/endpoint.

About this API

When you call PUT /v1/endpoint/disable, Exchange disables the endpoint that is associated with the authentication key that you include as the authorization bearer in the API call.

Request

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

Request format (as a CURL command)

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

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

PUT v1/endpoint/disable provides responses as follows.

PUT /v1/endpoint/{endpoint_id}/reportfailure

Acoustic Exchange endpoint providers make this API call to Exchange to indicate that endpoint provisioning failed on the provider side and to provide a reason for the failure.

About this API

Exchange notifies Exchange users of endpoint status in a field on the Endpoints tab in the Exchange user interface. As an endpoint provider, call PUT /v1/endpoint/{endpoint_id}/reportfailure to indicate a provisioning failure so that Exchange can indicate the failure on the Endpoints tab.

Depending on the provisioning process and requirements, the exchange of provisioning information between Exchange and the provider takes varying amounts of time. This API gives endpoint providers a means to report a provisioning failure after the provisioning process begins.

The endpoint provider can provide a reason for the failure in the JSON payload of the response. The size of the reason cannot exceed 512 bytes. Upon receipt of this API call, Exchange sets the status of the endpoint to FAILED and stores the reason in a database.

Note: The failure status displays on the Endpoints tab, the failure reason does not.
###Request
Direct the API call to the base URL that is assigned to your Exchange account.

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

curl -v 
-X PUT 
-H "Authorization: Bearer <endpoint-level authentication key>" 
-H "Content-Type: application/json"; charset=utf-8 
-d ’{“reason” : “<failure explanation>”},
https://<base URL>/v1/endpoint/{endpoint_id}/reportfailure

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

{
   "reason" :"<description>"
}

In the call, give the reason for the failed provisioning. Be concise.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

A successful call returns: 200 OK, true

GET v1/{endpointid}/status

As an endpoint provider, call Acoustic Exchange to determine the current status of an endpoint, based on an endpoint ID. For example, you can use the API to determine if an endpoint is deleted.

About this API

Call GET /v1/{endpoint id}/status to determine the current status of an endpoint that you specify by its unique endpoint ID. The call must specify an endpoint level authentication key as the authorization bearer.

When you call GET /v1/{endpoint id}/status with an endpoint authentication key, the response includes the current status of the endpoint in Acoustic Exchange.

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 endpoint status:

curl -v 
-X GET 
-H "Authorization: Bearer <endpoint-level authentication key>" 
https://<base URL>/v1/{endpoint id}/status

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

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. The possible statuses that can be returned are PENDING, ACTIVE, FAILED, or DELETED. For example, a successful call to GET /v1/{endpoint id}/status might indicate that the endpoint is pending final provisioning by the endpoint provider, as follows:

200 OK, "PENDING"
##GET v1/endpoint/refreshSegments
As an endpoint provider, call GET v1/endpoint/refreshSegments to refresh the list of audiences that are available for sharing and the list of audiences that are ready to receive audience data.

About this API

Exchange refreshes the list of available audiences every night. To refresh the list of audiences at other times of the day, call GET v1/endpoint/refreshSegments. Exchange contacts PULL-type audience producer endpoints and PUSH-type audience consumers to determine if new audience data is available.

The call must specify an account-level authentication key as the authorization bearer. Contact Acoustic to get the account-level authentication key for your account.

Request

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

The following example illustrates a request (using curl) to get an updated audience list:

curl -v 
-X GET 
-H "Authorization: Bearer <account-level authentication key>" 
https://<base URL> v1/endpoint/refreshSegments

The Authorization: Bearer must be an account-level authentication key.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

200 OK The body of the response contains the job ID. To check the status of the refresh job, call GET /v1/jobs/{jobCategory}/{job Id}.

403 Not authorized. There might be a problem related to the authentication key that you submitted in the call.