Endpoint API: Custom Endpoints

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

PUT /v1/endpoint

Register an endpoint with Acoustic Exchange.

Before you begin

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

Business users that want to use your application with Acoustic Exchange must give you an authentication key that they generate in the Acoustic 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 Acoustic Exchange that the Acoustic Exchange user grants permission for the endpoint to interact with Acoustic Exchange on behalf of the Acoustic Exchange user.

As a Acoustic 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 Acoustic Exchange.

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

About this API

Call v1/endpoint to register an IBM application, or approved IBM Business Partner application, as a custom endpoint in Acoustic Exchange on behalf of a registered Acoustic 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. Acoustic Exchange uses the information to present the endpoint in the Acoustic 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 Acoustic 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.

JSON

Requirements

(See notes below)

PUT /v1/endpoint

{
  "name" : "<string>",
  "description" : "<string>",
  "providerName" : "<string>",
  "url" : "<url>",
  "hashAlgorithm": "<string>",
  
   

A.

Identify and describe the endpoint

  "endpointTypes" : 
    {
    "event" : 
      {
      "source" : 
        {
        "enabled" : <boolean>,
        },
      "destination" : 
        {
        "enabled" : <boolean>,
        "url" : "<url>",
        "destinationType" : <string> 
        }  
      },    

B.

Enable event publishers and subscribers

    "segment" : 
      {
      "source" : 
        {
        "enabled" : true,
        "url" : "<url>", 
        "producerType" : <string> 
        "dataWindow" : <days>
        },
      "destination" : 
        {
        "enabled" : <boolean>,
        "destinationType" : <string>
        "url" : "<url>"
        }
      }
    },

C.

Enable audience sources and destinations

  "marketingDatabasesDefinition" : 
  {
    "marketingDatabases" :  
    [
      {                  
      "name" :  "<string>", 
      "id": <string>,

D.

Identify an audience database (optional)

     "identifiers" : 
      [
        { 
        "name" : "<string>",
        "type" : "<identityType>",
        "hashMode": "<string>,
        "hashAlgorithm": "<string>",
        "isRequired": <true|false>,
        "isEventOnly": <true|false>
        
       
        }
      ],  

E.

Specify contact identifiers

    "attributes" : 
      [
        { 
        "name" : "<string>",          
        "type" : "<string>",
        "isRequired" : <boolean>,
        "hashMode": "<string>,
        "hashAlgorithm": "<string>", 
        "isRequired": <true|false>
        }
      ]
      }
    ]      
  }
  "notificationKey": "<number>"
}

F.

Specify audience attributes

A: Identify and describe the endpoint

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

Specify a URL that Acoustic 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.

Property Use Data type Valid value Description
name Required String As defined by your business Name of the business application. Example: Mobile Customer
Engagement
.
description Optional String As defined by your business

The Acoustic Exchange interface displays the description that you enter here. Be concise.

Example: Mobile app push notifications.

providerName Required String As defined by your business

Name of the endpoint provider. The Acoustic Exchange interface displays the name that you enter
here. Be concise.

Example: IBM

url Optional URL As defined by your business A single global URL that Acoustic Exchange uses to communicate with the endpoint, for all
endpoint types. Example: “https://api.example.com/event/”.
For specific endpoint types, you can define URLs that supersede the URL value that
you enter here.
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.

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.

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.

For other endpoint type

url Optional URL Valid URL

To override the global URL, enter a URL here to receive event data at a URL that
is not the same as the global URL.

Otherwise, can be null.

destinationType Optional String

push

pull

Default: push

Push: allows Acoustic Exchange to push data to the global URL for the endpoint or to the address that you specify with the url property.

Pull: Acoustic Exchange prepares and stores event data for download and waits for the endpoint to retrieve the data.

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.

Property Use Data type Valid value Description
source Required for audience producers Not applicable Not applicable Enter values for source properties if the endpoint is a segment source (audience producer).
destination Required for audience consumers Not applicable Not applicable Enter values for destination properties if the endpoint is an segment destination (audience consumer).
enabled Required Boolean true | false

Enable either source or destination.

url Optional URL Valid URL

To override the global URL, enter a URL here to receive source data at a URL that is not the same as the global URL.

Otherwise, can be null.

producerType Required for audience sources String

push

pull

Default: Pull

Push: allows the endpoint to push audience data to Acoustic Exchange.

Pull: Acoustic Exchange pulls audience data and metadata from the
endpoint, by using the global URL for the endpoint or the address that you specify
with the url property.

destinationType Required for audience destinations String

push

pull

Push: allows Acoustic Exchange to push audience data to the global URL for the endpoint or to the address that you specify with the url property.

Pull: Acoustic Exchange prepares and stores audience data for download and waits for the endpoint to retrieve the data.

dataWindow Optional Integer Number of days Acoustic Exchange users can specify a date range to limit how much audience 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.

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.

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

E: Specify contact identifiers

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.

Property Use Data type Valid value Description
name Required String As defined in your business systems Name of the identifier attribute as provided by the endpoint. For example,
personal_email.
type Required Identity type As defined in your business systems

Indicate the type of identifier. If possible, match the type to a Acoustic Exchange identity key. For example, email.

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

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.

Property Use Data type Valid value Description
name Required String As defined in your business systems Name of the attribute. For example, home_address or
billing_address.
type Required String

String

Number

The data format of the attribute.
isRequired Required Boolean

true | false

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. (You can leave this field empty.)

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, this property specifies the algorithm that used by the producer to hash the identifier or attribute.
isRequired Required Boolean

true | false

Indicates whether the source endpoint must specify the identifier or attribute.
notificationKey Optional Number As defined in your business systems The notification key that is used with subscription notifications.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

PUT v1/endpoint provides responses as follows.

Code Description

200 – 299

Success. The endpoint is registered with Acoustic Exchange for the Acoustic Exchange user that is associated
with the authentication key that you provided.

400 – 499

There is a problem with the API request. Examine the request for errors.

500 – 599

System error. Contact IBM for assistance.

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):

curl -v 
  -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.

JSON

Requirements

(See notes below)

PUT v1/endpointattributes
 
{
"attributes":
   {
    "<name1>":"<value1>",
    "<name2>":"<value2>",
    "<name3>":"<value3>"
   } 
} 

A.

Enter connection and authentication attributes

A: Enter connection and authentication attributes

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

Property Use Data type Valid value Description
Attributes Required Enter connection details and authentication credentials as defined by the endpoint.
name Required As defined by the endpoint. As defined by the endpoint.

Name of the connection or authentication attribute.

For example: “clientSecret

value Required As defined by the endpoint. As defined by the endpoint. Enter the value that the endpoint specifies and requires. The value is specific to the Acoustic Exchange account that needs to access the endpoint.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

PUT <base URL>/v1/endpointattributes/authkey/"<account authentication
key>"
provides responses as follows.

Code Description

200 – 299

Success. Acoustic Exchange received the connection and authentication values and asscoiated them with a
registered endpoint and Acoustic Exchange account.

400 – 499

There is a problem with the API request. Examine the request for errors.

500 – 599

System error. Contact IBM for assistance.

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 Acoustic Exchange. The
description can include various endpoint characteristics that you specify as additional query
parameters in the API call.

About this API

When Acoustic Exchange users register an endpoint, they generate an authentication key which is specific to the Acoustic Exchange user account and the registered endpoint. Calls to Acoustic Exchange APIs on behalf of a Acoustic 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, Acoustic 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://<baseURL>/v1/endpoint?segment=true&source=true&
loadSegments=true&startRecord=1&pageSize=20

Query parameter Description
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.

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 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
  • Name for each segment
  • Segment type
  • 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 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.

JSON

Requirements

[
   {
   "id":"<first segment ID>",
   "name":"<first segment (audience) name>",
   "description": "<first audience description>",
   "type": "<segment type>",
   "segment_attributes": 
      [
         {
         "name": "<first attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<second attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<(n) attribute name>",
         "type": "<data type>"
         }
      ]
   },
   {
   "id":"<second segment ID>",
   "name":"<second segment (audience) name>",
   "description": "<second audience description>",
   "type": "<segment type>",
   "segment_attributes": 
      [
         {
         "name": "<first attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<second attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<(n) attribute name>",
         "type": "<data type>"
         }
      ]
   },
   {
   "id":<(n) segment ID>,
   "name":"<(n) segment (audience) name>",
   "description": "<(n) audience description>",
   "type": "<segment type>",
   "segment_attributes": 
      [
         {
         "name": "<first attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<second attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<(n) attribute name>",
         "type": "<data type>"
         }
      ]
   }
]

Available audiences

(See notes below)

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.

Property Use Data type Valid value Description
id

Required

If the segment ID is not a string

long As defined by your business

Unique value that Acoustic Exchange can use to identify the segment.

id_string

Required

If the segment ID is a string

string As defined by your business

Unique value that Acoustic Exchange can use to identify the segment.

name Required string As defined by your business

Unique name that Acoustic Exchange can use to identify the segment.

Acoustic Exchange uses the name that you provide in the Acoustic Exchange user interface to identify the segment as available
for selection.

description Optional string text A brief description of the segment. For example, NewOptOuts.
type Optional string

Contact Lists

Databases

Queries

Specify one of the audience types that Acoustic Exchange supports. If you do not specify an audience type,
Acoustic Exchange sets the type to “Contact Lists”.
segment_ attributes Optional Each audience can define one or more multiple attributes. This section lists the name and
data type for each audience attribute that the endpoint supports.

name

(attribute name)

Required string As defined by your business Name of the attribute.

type

(attribute data type)

Required string As defined by your business The data format of the attribute.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

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

Code Description

200 – 299

true: The segments are successfully uploaded to Acoustic Exchange.

false: The segments are not uploaded successfully.

308

Return error code 308 in response to the call if you do not support adding a list of records to audience data that is ready for import or export but want to perform some other action instead. Include the alternate action in the response, as follows.

{
  "shareAction": "REPLACE"
}  
(example only)

400 – 499

There is a problem with the API request. Examine the request for errors.

501

Return error code 501 in response to the call if you do not support adding a list
of records to audience data that is ready for import or export.

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.

JSON

Requirements

[
   {
   "id":<first segment ID>,
   "name":"<first segment (audience) name>",
   "description": "<first audience description>",
   "type":"<segment type>",
   "segment_attributes": 
      [
         {
         "name": "<first attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<second attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<(n) attribute name>",
         "type": "<data type>"
         }
      ]
   },
   {
   "id":<second segment ID>,
   "name":"<second segment (audience) name>",
   "description": "<second audience description>",
   "type":"<segment type>",
   "segment_attributes": 
      [
         {
         "name": "<first attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<second attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<(n) attribute name>",
         "type": "<data type>"
         }
      ]
   },
   {
   "id":<(n) segment ID>,
   "name":"<(n) segment (audience) name>",
   "description": "<(n) audience description>",
   "type":"<segment type>",
   "segment_attributes": 
      [
         {
         "name": "<first attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<second attribute name>",
         "type": "<data type>"
         },
         {
         "name": "<(n) attribute name>",
         "type": "<data type>"
         }
      ]
   }
]

Available audiences

(See notes below)

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.

Property Use Data type Valid value Description
id Required long As defined by your business

Unique value that Acoustic Exchange can use to identify the segment.

id_string Required string As defined by your business

Unique value that Acoustic Exchange can use to identify the segment.

name Required string As defined by your business

Unique name that Acoustic Exchange can use to identify the segment.

Acoustic Exchange uses the name of the segment to display the segment in the Acoustic Exchange user interface.

description Optional string text A brief description of the segment. For example,NewOptOuts.
type Optional string

Contact Lists

Databases

Queries

Specify one of the audience types that Acoustic Exchange supports. If you do not specify an audience type,
Acoustic Exchange sets the type to “Contact Lists”.
segment_ attributes Optional Each audience can define one or more multiple attributes. This section lists the name and
data type for each audience attribute that the endpoint supports.

name

(attribute name)

Required string As defined by your business Name of the attribute.

type

(attribute data type)

Required string As defined by your business The data format of the attribute.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

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

Code Description

200 – 299

true: The segments are successfully replaced in Acoustic Exchange.

false: The segments are not replaced successfully.

400 – 499

There is a problem with the API request. Examine the request for errors.

DELETE /v1/endpoint/{endpointId}/segments

Clear the list on Acoustic Exchange that identifies segments that are ready for export or import to Acoustic 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 Acoustic Exchange.

Endpoints that make this API call must be registered with Acoustic 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 Acoustic Exchange. You must also provide the authentication key that is associated with a Acoustic Exchange user account.

Request

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

Code Description

200 – 299

true: All segments for the specified endpoint are removed from
Acoustic Exchange.

false: The segments are not removed.

400 – 499

There is a problem with the API request. Examine the request for errors.

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

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

About this API

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

Endpoints that make this API call must be registered with Acoustic 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 a Acoustic Exchange user account.

Request

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

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

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

Code Description

200 – 299

true: The segment is removed from Acoustic Exchange.

false: The segment is not removed.

308

Return error code 308 in response to the call if you do not support removing audience data that is ready for import or export but want to perform some other action instead. Include the alternate action in the response.

400 – 499

There is a problem with the API request. Examine the request for errors.

501

Return error code 501 in response to the call if you do not support removing audience data that is ready for import or export.

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.

Code Description

200

True. The endpoint is enabled.

304

Endpoint status is not changed.

403

Not authorized.

500 – 599

System error. Contact IBM for assistance.

PUT /v1/endpoint/disable

Call this API to disable 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/disable, Acoustic 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 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/disable

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

PUT v1/endpoint/disable provides responses as follows.

Code Description

200

True. The endpoint is disabled.

304

Endpoint status is not changed.

403

Not authorized.

500 – 599

System error. Contact IBM for assistance.

PUT /v1/endpoint/{endpoint_id}/reportfailure

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

About this API

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

Depending on the provisioning process and requirements, the exchange of provisioning information between Acoustic 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 ize of the reason cannot exceed 512 bytes. Upon receipt of this API call, Acoustic 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 Acoustic 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.

Request JSON
{
   "reason" :"<description>"
}

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

Property Use Data type Valid value Description
reason Required String Text to describe the problem. A brief reason why an endpoint provisioning request failed.

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

Acoustic 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. Acoustic 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 IBM to get the account-level authentication key for your account.

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

1 comment on"Endpoint API: Custom Endpoints"

  1. Michael Kollmann October 31, 2018

    Url “GET v1/{endpointid}/status” is wrong.

Join The Discussion

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