APIs to individually register and manage
PUT /v1/endpoint
Register an endpoint with
Before you begin
You register an endpoint with
Business users that want to use your application with
As an
Confirm that you received an authentication key from the
About this API
Call v1/endpoint to register an
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
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.
<PUT /v1/endpoint
{
"name" : "
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
Specify a URL that
As required, you can specify a hashing algorithm to obscure potentially sensitive identity and attribute data.
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
Example: Mobile app push notifications.
providerName
Required
String
As defined by your business
Name of the endpoint provider. The
here. Be concise.
Example: Acoustic
url
Optional
URL
As defined by your business
A single global URL that
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
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.
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.
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
Pull:
destinationType
Required for audience destinations
String
push
pull
Push: allows
Pull:
dataWindow
Optional
Integer
Number of days
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.
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.
id
Optional
String
As defined in your business systems.
Identifier for the source database, as applicable.
E: Specify contact identifiers
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
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:
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.
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:
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
PUT v1/endpoint provides responses as follows.
200-299
Success. The endpoint is registered with
400-499
There is a problem with the API request. Examine the request for errors.
500-599
System error. Contact
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.
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.
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
Response
PUT <base URL>/v1/endpointattributes/authkey/"<account authentication key>" provides responses as follows.
200-299
Success.
400-499
There is a problem with the API request. Examine the request for errors.
500-599
System error. Contact
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
About this API
When
When you call GET /v1/endpoint with an endpoint authentication key,
Request
Direct the API call to the base URL that is assigned to your
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
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
DELETE /v1/endpoint
Delete an
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
Request
Direct the API call to the base URL that is assigned to your
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
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
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 youraccount.
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.
[
{
"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>"
}
]
id
Required
If the segment ID is not a string
long
As defined by your business
Unique value that
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
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
POST /v1/endpoint/{endpointId}/segments provides responses as follows.
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.
[
{
"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>"
}
]
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
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
PUT /v1/endpoint/{endpointId}/segments provides responses as follows.
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
About this API
Endpoints that provide audience data make this call to
Endpoints that make this API call must be registered with
To call this API, you must provide the endpoint ID for the endpoint that provided the segment (audience data) that was uploaded to
Request
Direct the API call to the base URL that is assigned to your
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
DELETE /v1/endpoint/{endpointId}/segments provides responses as follows.
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
About this API
Endpoints that provide audience data make this call to
Endpoints that make this API call must be registered with
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
Request
Direct the API call to the base URL that is assigned to your
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
DELETE /v1/endpoint/{endpointId}/segments/<segmentID> provides responses as follows.
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.
200
True. The endpoint is enabled.
304
Endpoint status is not changed.
403
Not authorized.
500-599
System error. Contact
PUT /v1/endpoint/disable
Call this API to disable an endpoint that has been registered on behalf of an
Before you begin
Register the endpoint using PUT v1/endpoint.
About this API
When you call PUT /v1/endpoint/disable,
Request
Direct the API call to the base URL that is assigned to your
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
PUT v1/endpoint/disable provides responses as follows.
200
True. The endpoint is disabled.
304
Endpoint status is not changed.
403
Not authorized.
500-599
System error. Contact
PUT /v1/endpoint/{endpoint_id}/reportfailure
Acoustic Exchange endpoint providers make this API call to
About this API
Depending on the provisioning process and requirements, the exchange of provisioning information between
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,
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
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.
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 -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
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
The call must specify an account-level authentication key as the authorization bearer. Contact
Request
Direct the API call to the base URL that is assigned to your
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
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