Endpoint API/ Custom endpoints

Suggest Edits

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

PUT /v1/endpoint

Before you begin

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

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

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

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

About this API

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

Example requests (as curl commands):

To register endpoints that publish or subscribe to events:

cURL

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

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)

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 requires to identify the endpoint and display it in the user interface.

Specify a URL that 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 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 interface displays the name that you enter
here. Be concise.

Example: Acoustic

url

Optional

URL

As defined by your business

A single global URL that 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 uses when destination endpoints require that 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

Enter values for source properties if the endpoint is an event publisher.

destination

Required for event subscribers

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.

source

Required for audience producers.

Not applicable

Enter values for source properties if the endpoint is a segment source (audience producer).

destination

Required for audience consumers.

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 .

Pull: 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 to push audience data to the global URL for the endpoint or to the address that you specify with the URL property.

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

dataWindow

Optional

Integer

Number of days

users can specify a date range to limit how much audience data to upload to . 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

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.

Optional

String

As defined in your business systems.

Identifier for the source database, as applicable.

E: Specify contact identifiers

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

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

Optional

String

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

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

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 for the 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 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

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

Name of the connection or authentication attribute.

For example: “clientSecret“

value

Required

As defined by the endpoint.

Enter the value that the endpoint specifies and requires. The value is specific to the account that needs to access the endpoint.

Response

public APIs return standard HTTP 1.1 response codes.

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

200-299

Success. received the connection and authentication values and associated them with a registered endpoint and account.

400-499

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

500-599

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

About this API

When users register an endpoint, they generate an authentication key which is specific to the user account and the registered endpoint. Calls to APIs on behalf of an 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, 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 account.

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

cURL

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

public APIs return standard HTTP 1.1 response codes.

DELETE /v1/endpoint

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

Request

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

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

JSON

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

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 .

About this API

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

Request format (as a curl command):

cURL

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

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.

Text

[
  {
   "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

Required

If the segment ID is not a string

long

As defined by your business

Unique value that 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 supports. If you do not specify an audience type, 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

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

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

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.

Text

[
  {
   "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

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 supports. If you do not specify an audience type,
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 attributes.

Response

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 that identifies segments that are ready for export or import to .

About this API

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

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

Request

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

Example request (as a curl command):

cURL

curl -v

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

Response

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 .

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 that identifies segments that are ready for export or import to .

About this API

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

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

Request

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

Example request (as a curl command):

cURL

curl -v

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

Response

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

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)

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

PUT /v1/endpoint/disable

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

Before you begin

About this API

When you call PUT /v1/endpoint/disable, 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 account.

Request format (as a CURL command)

cURL

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

Response

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

PUT /v1/endpoint/{endpoint_id}/reportfailure

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

About this API

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

Depending on the provisioning process and requirements, the exchange of provisioning information between 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, 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 account.

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

cURL

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.

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

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

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

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

Request

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

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

cURL

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

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.

Updated 7 months ago