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.

JSONRequirements (See notes below)
<PUT /v1/endpoint{
"name" : "",
"description" : "",
"providerName" : "",
"url" : "",
"hashAlgorithm": "",
/>
A. Identify and describe the endpoint
"endpointTypes" :
{
"event" :
{
"source" :
{
"enabled" : ,
},
"destination" :
{
"enabled" : ,
"url" : "",
"destinationType" :
}
},
B. Enable event publishers and subscribers
"segment" :
{
"source" :
{
"enabled" : true,
"url" : "",
"producerType" :
"dataWindow" :
},
"destination" :
{
"enabled" : ,
"destinationType" :
"url" : ""
}
}
},
C. Enable audience sources and destinations
"marketingDatabasesDefinition" :
{
"marketingDatabases" :
[
{
"name" : "",
"id": ,
D. Identify an audience database (optional)
"identifiers" :
[
{
"name" : "",
"type" : "",
"hashMode": ",
"hashAlgorithm": "",
"isRequired": <true|false>,
"isEventOnly": <true|false> } ],
E. Specify contact identifiers
"attributes" :
[
{
"name" : "",
"type" : "",
"isRequired" : ,
"hashMode": ",
"hashAlgorithm": "",
"isRequired": <true|false>
}
]
}
]
}
"notificationKey": ""
}
F. Specify audience attributes

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.

PropertyUseData typeValid valueDescription
nameRequiredStringAs defined by your businessName of the business application. Example: Mobile Customer Engagement.
descriptionOptionalStringAs defined by your businessThe Exchange interface displays the description that you enter here. Be concise.Example: Mobile app push notifications.
providerNameRequiredStringAs defined by your businessName of the endpoint provider. The Exchange interface displays the name that you enter
here. Be concise.Example: Acoustic
urlOptionalURLAs defined by your businessA single global URL that 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.
hashAlgorithmOptionalStringMD5SHA1SHA256EMAIL_SHA256PHONE_SHA256The hashing algorithm that Exchange uses when destination endpoints require that 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.

PropertyUseData typeValid valueDescription
sourceRequired for event publishersNot applicableNot applicableEnter values for source properties if the endpoint is an event publisher.
destinationRequired for event subscribersNot applicableNot applicableEnter values for destination properties if the endpoint is an event subscriber.
enabledRequiredBooleantrue | falseEnable either source or destination.For other endpoint type
urlOptionalURLValid URLTo 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.
destinationTypeOptionalStringpushpullDefault: pushPush: 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.

sourceRequired for audience producers.Not applicableNot applicableEnter values for source properties if the endpoint is a segment source (audience producer).
destinationRequired for audience consumers.Not applicableNot applicableEnter values for destination properties if the endpoint is an segment destination (audience consumer).
enabledRequiredBooleantrue | falseEnable either source or destination.
urlOptionalURLValid URLTo 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
producerTypeRequired for audience sourcesStringpushpullDefault: PullPush: allows the endpoint to push audience data to Exchange.Pull: 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.
destinationTypeRequired for audience destinationsStringpushpullPush: allows Exchange to push audience data to the global URL for the endpoint or to the address that you specify with the URL property.Pull: Exchange prepares and stores audience data for download and waits for the endpoint to retrieve the data.
dataWindowOptionalIntegerNumber of daysExchange users can specify a date range to limit how much audience data to upload to 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.

PropertyUseData type
nameRequired if you identify the audience database.StringAs defined in your business systems.Name of the database that provides the source and schema of the source for identity lookup.
idOptionalStringAs 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, 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.

nameRequiredStringAs defined in your business systemsName of the identifier attribute as provided by the endpoint. For example,
personal_email.
typeRequiredIdentity typeAs defined in your business systemsIndicate the type of identifier. If possible, match the type to an 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.
hashModeOptionalStringNONEHASHEDREQUIREDIf 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: 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.
hashAlgorithmOptionalStringMD5SHA1SHA256EMAIL_SHA256PHONE_SHA256If the hashMode is REQURED, then this property specifies the algorithm that the audience source endpoint uses to hash the identifier or attribute.
isRequiredOptionalStringtrue | falseIndicates whether the source endpoint must specify the identifier or attribute.
isEventOnlyOptionalBooleantrue|falseIndicates 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.

PropertyUseData typeValid valueDescription
nameRequiredStringAs defined in your business systemsName of the attribute. For example, home_address or
billing_address.
typeRequiredStringStringNumberThe data format of the attribute.
isRequiredRequiredBooleantrue | false
hashModeOptionalStringNONEHASHEDREQUIREDIf 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: 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.
hashAlgorithmOptionalStringMD5SHA1SHA256EMAIL_SHA256PHONE_SHA256If the hashMode is REQURED, this property specifies the algorithm that used by the producer to hash the identifier or attribute.
isRequiredRequiredBooleantrue | falseIndicates whether the source endpoint must specify the identifier or attribute.
notificationKeyOptionalNumberAs 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.

CodeDescription
200-299Success. The endpoint is registered with Exchange for the Exchange user that is associated with the authentication key that you provided.
400-499There is a problem with the API request. Examine the request for errors.
500-599System error. Contact Acoustic 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):

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

JSONRequirements (See notes below)
PUT v1/endpointattributes{
"attributes":
{
"":"",
"":"",
"":""
}
}
A. Enter connection and authentication attributes

A: Enter connection and authentication attributes

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

PropertyUseData typeValid valueDescription
AttributesRequiredEnter connection details and authentication credentials as defined by the endpoint.
nameRequiredAs defined by the endpoint.As defined by the endpoint.Name of the connection or authentication attribute.For example: “clientSecret“
valueRequiredAs defined by the endpoint.As defined by the endpoint.Enter the value that the endpoint specifies and requires. The value is specific to the Exchange account that needs to access the endpoint.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

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

200-299Success. Exchange received the connection and authentication values and associated them with a registered endpoint and Exchange account.
400-499There is a problem with the API request. Examine the request for errors.
500-599System error. Contact Acoustic 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 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

Query parameterDescription
destinationReturn descriptions of audience and event destination endpoints.Example: destination=true
eventReturn descriptions of event source and event destination endpoints.Example:event=true
loadEventsUse with event. Return the known eventTypes for an event producer.Example: event=true&loadEvents=true
loadSegmentsUse with segment. Return the known segments for a segment producer.Example: segment=true&loadSegments=true
pageSizePass 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
searchByDescriptionPass a search criteria that might match a value in a segment description of a segment.Example: searchByDescription=opt-in.
searchByNamePass a search criteria that might match the name of a segment.Example: searchByName=Recent opt-ins.
segmentReturn descriptions of segment source and segment
destination endpoints.Example:segment=true
sourceReturn descriptions of audience and event source endpoints.Example: source=true
startRecordUse 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 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.

JSONRequirements
[
{
"id":"",
"name":"<first segment (audience) name>",
"description": "",
"type": "",
"segment_attributes":
[
{
"name": "",
"type": ""
},
{
"name": "",
"type": ""
},
{
"name": "<(n) attribute name>",
"type": ""
}
]
},
{
"id":"",
"name":"<second segment (audience) name>",
"description": "",
"type": "",
"segment_attributes":
[
{
"name": "",
"type": ""
},
{
"name": "",
"type": ""
},
{
"name": "<(n) attribute name>",
"type": ""
}
]
},
{
"id":<(n) segment ID>,
"name":"<(n) segment (audience) name>",
"description": "<(n) audience description>",
"type": "",
"segment_attributes":
[
{
"name": "",
"type": ""
},
{
"name": "",
"type": ""
},
{
"name": "<(n) attribute name>",
"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 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 Exchange supports. If you do not specify an audience type, 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)RequiredstringAs defined by your businessName of the attribute.
type (attribute data type)RequiredstringAs defined by your businessThe 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.

CodeDescription
200-299true: The segments are successfully uploaded to Acoustic Exchange.false: The segments are not uploaded successfully.
308Return 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-499There is a problem with the API request. Examine the request for errors.
501Return 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.

JSONRequirements
[
{
"id":,
"name":"<first segment (audience) name>",
"description": "",
"type":"",
"segment_attributes":
[
{
"name": "",
"type": ""
},
{
"name": "",
"type": ""
},
{
"name": "<(n) attribute name>",
"type": ""
}
]
},
{
"id":,
"name":"<second segment (audience) name>",
"description": "",
"type":"",
"segment_attributes":
[
{
"name": "",
"type": ""
},
{
"name": "",
"type": ""
},
{
"name": "<(n) attribute name>",
"type": ""
}
]
},
{
"id":<(n) segment ID>,
"name":"<(n) segment (audience) name>",
"description": "<(n) audience description>",
"type":"",
"segment_attributes":
[
{
"name": "",
"type": ""
},
{
"name": "",
"type": ""
},
{
"name": "<(n) attribute name>",
"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 Exchange supports. If you do not specify an audience type,
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)RequiredStringAs defined by your businessName of the attribute.
type (attribute data type)RequiredStringAs defined by your businessThe data format of the attributes.

Response

Exchange public APIs return standard HTTP 1.1 response codes.

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

CodeDescription
200-299true: The segments are successfully replaced in Acoustic Exchange.false: The segments are not replaced successfully.
400 – 499There 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 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.

CodeDescription
200-299true: All segments for the specified endpoint are removed from Exchange.false: The segments are not removed.
400-499There 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 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.

CodeDescription
200-299true: The segment is removed from Acoustic Exchange.false: The segment is not removed.
308Return 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-499There is a problem with the API request. Examine the request for errors.
501Return 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.

CodeDescription
200True. The endpoint is enabled.
304Endpoint status is not changed.
403Not authorized.
500-599System error. Contact Acoustic for assistance.

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.

CodeDescription
200True. The endpoint is disabled.
304Endpoint status is not changed.
403Not authorized.
500-599System error. Contact Acoustic for assistance.

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.

PropertyUseData typeValid valueDescription
reasonRequiredStringText 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 -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.