Account-level API

MitchM
Published on May 22, 2017 / Updated on August 26, 2019

To manage data syndications for an entire Acoustic Exchange user account, you can call Acoustic Exchange account level APIs.

An Acoustic Exchange user account can be associated with multiple endpoints, each representing a different business application. In such cases, endpoints for the Acoustic Exchange account can be a combination of event or audience producers or consumers. To call account-level APIs, you must have account level access to Acoustic Exchange in the form of account-level authentication keys and account IDs.

GET /v1/endpoint

Call GET /v1/endpoint with an account-level authentication key to get a description for all endpoints that are associated with a specific Acoustic Exchange user account. The description can include various endpoint characteristics that you specify as additional query parameters in the API call.

About this API

To get descriptions for all endpoints that are associated with a particular Acoustic Exchange account, you must include an account-level authentication key as the authorization bearer for the API call. The authentication key must be an account level authentication key that is provided to you by Acoustic Exchange.

Note: To make this call successfully, you must have access authorization across all endpoints that are registered for the user account.

When you call GET /v1/endpoint with an account-level authentication key, Acoustic Exchange returns descriptions for all endpoints that are associated with the account.

To return information for only one endpoint that is registered to an Acoustic Exchange account, you can include the endpoint ID as a URL parameter in the call.

In the URL for the call, you can include additional optional URL parameters to request specific characteristics for each endpoint that is registered to the account. Separate parameters with &.

Request

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

The response lists the endpoint properties as they were entered during event registration with PUT v1/endpoint.

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

Request format (as a curl command):

curl -v 
-X GET 
-H "Authorization: Bearer <account authentication key>" 
<base URL>/v1/endpoint?<parameter 1>&<parameter 2>&<parameter n>

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

For example, calling the following URL returns descriptions for up to 20 segments that provide audience data from the various endpoints that are registered with Acoustic Exchange on behalf of the Acoustic Exchange account that is associated with the account-authentication key.

<base URL>/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`
`includeSegmentIDString`	Use when `loadSegments` is set to true and the source segment ID is a string. Returns the `segmentIDString` for the source segment. Example: `loadSegments=true&includeSegmentIDString=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`
`endpointId`	Include this as a URL parameter to specify a single endpoint ID. The call returns results only for the endpoint that you specify. Example: `endpointId=12345` Note: Acoustic Exchange supports this parameter only when you include an account-level authentication key as the authorization bearer in the API call.
`includeBilling`	Include this as a URL parameter to return the billing category for the endpoint. Example: `includeBilling=true` Note: Acoustic Exchange supports this parameter only when you include an account-level authentication key as the authorization bearer in the API call.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

GET <base URL>/v1/endpoint provides responses as follows.

Code	Description
200 – 299	Success. The response lists the endpoint properties as entered during event registration with `PUT v1/endpoint`.
400 – 499	There is a problem with the API request. Examine the request for errors.
500 – 599	System error. Contact Acoustic Exchange Support.

DELETE /v1/endpoint/{endpointId}

Delete a specific registered endpoint in Acoustic Exchange. This API call requires account level
authorization.

About this API

Call DELETE /v1/endpoint/{endpointId}remove an endpoint from Acoustic Exchange. Calling DELETE /v1/endpoint/{endpointId} provides the same request options and the same responses as DELETE /v1/endpoint. However, because you call DELETE /v1/endpoint/{endpointId} from the account level, you must specify the endpoint ID as a URL parameter.

Request

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

Example request (as a curl command):

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

Note: Specify the endpointID as a URL parameter in the API call.

Other than including the endpoint ID as a parameter in the API call, the details of the API request and the API response are the same as PUT /v1/endpoint. For more information about the PUT /v1/endpoint API, see DELETE /v1/endpoint.

PUT /v1/endpoint/{endpointId}

About this API

Call PUT v1/endpoint/{endpointID} to register an Acoustic Exchange application, or approved Acoustic Exchange Business Partner application, as an endpoint in Acoustic Exchange on behalf of a registered Acoustic Exchange user. Calling PUT /v1/endpoint/{endpointId} API provides the same request options
and the same responses as PUT /v1/endpoint. However, because you call PUT v1/endpoint/{endpointID} from the account level, you must specify an endpoint ID as a URL parameter.

Request

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

Example request, in this example to register as an event endpoint, (as a curl command):

 
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/<endpoint ID>

Note: Specify the endpointID as a URL parameter in the API call.

PUT /v1/endpoint/database

You can use this API to modify the database identification information that is associated
with an endpoint.

About this API

There are some provisioning or integration use cases in which a database name or ID must be modified after endpoint registration. Acoustic Exchange provides the PUT /v1/endpoint/database API if such a use case becomes necessary for your application.

Request

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

You can use either an endpoint level or an application level authentication key as the authorization bearer for the call. If you use an application level authentication key, you must include the endpoint ID in the call as a means to identify the endpoint. If you use an endpoint level authentication key, the key is used to identify the endpoint.

Request format (as a curl command):

curl -X PUT 
  <base URL>/v1/endpoint/database 
  -H 'accept-charset: UTF-8' 
  -H 'authorization: Bearer <endpoint or application authentication key>' 
  -H 'cache-control: no-cache' 
  -H 'content-type: application/json' 
  -H 'postman-token: <token>' 
  -d {
      "endpointId": <endpoint ID>,
      "databaseId": "<database ID>",
      "marketingDatabaseName": "<database name>"
}

Property	Use	Description
`endpointId`	Required if: You are using an application authentication key as authentication bearer.	The `endpointId` is used to identify which endpoints identification information is to be modified.
`databaseId`	Required	Enter the alphanumeric ID of the database that is to be associated with an endpoint.
`marketingDatabaseName`	Required if: There are multiple databases that are associated with an endpoint.	The name or names of the databases that are associated with an endpoint.

Property

Use

Description

endpointId

Required if:

You are using an application authentication key as authentication
bearer.

The endpointId is used to identify which endpoints identification information is to be modified.

databaseId

Required

Enter the alphanumeric ID of the database that is to be associated with an endpoint.

marketingDatabaseName

Required if:

There are multiple databases that are associated with an
endpoint.

The name or names of the databases that are associated with an endpoint.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

PUT <base URL>/v1/endpoint/database provides responses as follows.

Code	Description
200 – 299	Success.
400 – 499	There is a problem with the API request. Examine the request for errors.
500 – 599	System error. Contact Acoustic Exchange Support for assistance.

PUT /v1/endpoint/disable/{endpointId}

If you manage multiple endpoints for an Acoustic Exchange account, you can disable a specific registered endpoint by specifying the endpoint ID when you call PUT /v1/endpoint/disable and specify an account-level authentication key.

Before you begin

About this API

To disable one of multiple endpoints that are registered to an account, you must include an account-level authentication key as the authorization bearer for the API call. The authentication key must be an account-level authentication key that is provided to you by Acoustic Exchange.

Request

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

Add the endpoint ID of the endpoint that you want to disable as a parameter to the URL, as shown in the example.

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/<endpoint ID>

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

PUT v1/endpoint/disable/{endpoint ID} 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 Acoustic Exchange Support for assistance.

PUT /v1/endpoint/enable/{endpointId}

If you manage multiple endpoints for an Acoustic Exchange account, you can enable a specific registered endpoint by specifying the endpoint ID when you call PUT /v1/endpoint/enable and specify an account-level authentication key.

Before you begin

About this API

To enable one of multiple endpoints that are registered to an account, you must include an account-level authentication key as the authorization bearer for the API call. The authentication key must be an account-level authentication key that is provided to you by Acoustic Exchange.

Request

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

Add the endpoint ID of the endpoint that you want to enable as a parameter to the URL, as shown in the example.

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/<endpoint ID>

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

PUT <base URL>/v1/endpoint/enable/{endpoint ID} 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 Acoustic Exchange for assistance.

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

Get the details of a specific audience within an endpoint.

About this API

Call this API to get a description for a specific audience that is provided or received by an endpoint that is registered with Acoustic Exchange on behalf of an Acoustic Exchange user account. The call requires a valid authentication key, which is specific to the user account and endpoint.

Note: Information that you retrieve for a segment with this API appears in the Acoustic Exchange user interface as details that relate to an audience.

You must provide the following information to call this API:

Authentication key that is associated with an Acoustic Exchange user account
Endpoint ID for the endpoint in which the audience is defined
Segment ID for the segment that you want to describe

You must also have user authorization to access the endpoint.

Request

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

Example request (as a curl command):

curl -v 
    -X GET 
    -H "Authorization: Bearer 1234-abcd-5678-efgh" 
    <base URL>/v1/endpoint/<endpointID>/segments/{<segmentID>}

Response

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

Note: If the audience is a string and the query parameter includeSegmentIDString is set to true, then the call returns the property id_string in place of id.

JSON	Output (See notes below)
`{ "segment_attributes": [ {"name":"<attribute name>","type":<attribute type>}, ], "id":<segment ID>, B:Segment identification "name":"<segment name>", "description":<brief description> }`	A. Attributes
`"id":45311, "idString":null, "name":"100Cust", "description":null }`	B. Segment identification
`EXAMPLE: { "segment_attributes": [ {"name":"LIST_ID","type":null}, {"name":"MAILING_ID","type":null}, {"name":"RECIPIENT_ID","type":null}, {"name":"EMAIL","type":null}, {"name":"CRM Lead Source","type":null}, {"name":"cookieId","type":"0"}, {"name":"sessionId","type":"0"}, {"name":"Email","type":null} ],`	Example response

JSON

Output

(See notes below)

{
  "segment_attributes":
  [  
    {"name":"<attribute name>","type":<attribute type>}, 
  ],
  "id":<segment ID>,  B:Segment identification
  "name":"<segment name>",
  "description":<brief description>
}

Attributes

"id":45311,
  "idString":null,
  "name":"100Cust",
  "description":null
}

Segment identification

EXAMPLE:
{
  "segment_attributes":
  [  
    {"name":"LIST_ID","type":null},
    {"name":"MAILING_ID","type":null},
    {"name":"RECIPIENT_ID","type":null},
    {"name":"EMAIL","type":null},
    {"name":"CRM Lead Source","type":null},
    {"name":"cookieId","type":"0"},
    {"name":"sessionId","type":"0"},
    {"name":"Email","type":null}
  ],

Example response

A: Attributes

Property	Data type	Valid value	Description
`name`	string	As defined in the segment.	Name of the attribute, as defined during endpoint registration with `v1/endpoint`.
`type`	string (default) number boolean Timestamp (iso8601)	As defined in the segment.	Attribute type, as defined during endpoint registration with `v1/endpoint`.

Property

Data type

Valid value

Description

name

string

As defined in the segment.

Name of the attribute, as defined during endpoint registration with v1/endpoint.

type

string (default)

number

boolean

Timestamp (iso8601)

As defined in the segment.

Attribute type, as defined during endpoint registration with v1/endpoint.

B: Segment identification

Property	Data type	Valid value	Description
`id`	long	As defined by your business	Unique value that Acoustic Exchange can use to identify the segment.
`id_String`	string	As defined by your business	Unique values that Acoustic Exchange can use to identify segments.
`name`	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`	string	As defined by your business.	Brief description of the segment.

POST /v1/jobs/segmentExport

Create a job to share audience data from a source endpoint to a destination endpoint.
Additionally, you can use POST /v1/jobs/segmentExport to upload identity data to the Acoustic Exchange Identity Store.

About this API

The response that this API provides depends on the producer type of the audience source endpoint.

If the source endpoint is a PULL audience provider and the destination endpoint is a PUSH audience consumer: Acoustic Exchange automatically performs the entire process of uploading audience data from the source endpoint, joining audience identifiers if possible, and downloading the audience data to the destination endpoint.
If the source endpoint is a PUSH audience provider: Acoustic Exchange creates the export job but waits for the source endpoint to upload audience data. Acoustic Exchange puts the job in WAITING_TO_RECIEVE_DATA status. To continue the audience sharing process, the source endpoint must call POST /v1/jobs/{jobId}/data to upload the audience data to Acoustic Exchange.
If the source endpoint is a PULL audience consumer: Acoustic Exchange creates the export job but waits until the consumer audience data is ready to download. When consumer audience data is ready to download, the status of the job changes to READY_FOR_DOWNLOAD. To download the audience data, call GET /v1/jobs/{jobId}/segmentDataFiles/{fileName}.

Calling POST /v1/jobs/segmentExport from a segment producer endpoint to create a waiting segment export job makes it possible for Acoustic Exchange users to use the Acoustic Exchange user interface to upload audience data from the segment producer endpoint to Acoustic Exchange on demand.

Note: To make this call successfully, you must have access authorization across all endpoints that are registered for the user account.

Request

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

You must use an account-level authorization key as the authorization bearer for this API call.

Note: If the audience segment has a string segment ID, then the property segmentIDString should be defined in place of the property segmentID.

Example request (as a curl command):

curl -v 
  -X PUT
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -d '{
        "endpointID":<source endpointID>,
        "segmentID":<source segmentID>|"segmentIDString":<string segment ID (source)>,
        "segmentName":"<name of the segment>",
        "destinationEndpointID":<destination endpointID>,
        "destinationSegmentName":"<destination segment name>",
        "exportCategory":"<category>",
        "action": "<action type>",
        "sourceIdentifiers":["<soure identifiers>"],
        "destinationIdentifier":"<destination identifier>",
        "attributeMappings":{"<source attribute>":"<destination attribute>"},
        "updateIdentities":true|false
        "minCount":"<integer>",
        "scheduleDetails": {schedule}
       }'
     <base URL>/v1/jobs/segmentExport

The following table describes the JSON payload of the call.

JSON	Requirements
`{ "endpointID":<endpoint ID (source)>, "segmentID":<segment ID (source)>\|"segmentIDString":<string segment ID (source)>, "segmentName":<name of the segment>,`	A. Identify the source segment.
`"destinationEndpointID":<endpointID (destination)>, "destinationSegmentName":"<segment name (destination)>", "destinationSegmentDescription":"<segment description (source)>", "destinationSegmentID":"<destination Segment ID>", "exportCategory":"<category>",`	B. Identify the destination segment.
`"action": "<action type>",`	C. Specify the action of the call.
`"sourceIdentifiers":["<source identifier>,<source identifier>]", "destinationIdentifier":"<destination identifier>", "attributeMappings":{"<attribute (source)>":"<attribute (destination)>"},`	D. Specify source and destination identifiers, and attribute mapping.
`"updateIdentities":true\|false`	E. Indicate whether the Acoustic Exchange Identity Store is to be updated.
`"minCount":<inetger>,`	F. Set the minimum number of records to send to the destination.
`"scheduleDetails":{ "runNow":true\|false, "runRepeat":true\|false, "daysOfWeek":<day of the week>, "daysOfMonth":<day of the month>, "monthsOfYear":<months of the year>, "year":<the year>, "startHour":"<the hour to start>", "startMinute":"<the minute to start>", "startSecond":"<the second to start>", "startDate":"<the start date>", "endDate":<the end date>, "timeSliceStartDate":<date>, "timeSliceEndDate":<date> },`	G. Schedule the audience sharing.

A: Identify the source segment

Property	Use	Data type	Valid value	Description
`endpointID`	Required	Long	Specified by source endpoint	Define a unique value that Acoustic Exchange can use to identify the source endpoint.
`segmentID`	Required If segment ID is not a string	Long	Specified by source endpoint	Define a unique value that Acoustic Exchange can use to identify the source segment.
`segmentIDString`	Required If segment ID is a string	String	Specified by source endpoint	Define a unique value that Acoustic Exchange can use to identify the source segment. Note: Define this property only if the source segment ID is a string.
`segmentName`	Optional	Long	Specified by source endpoint	Define a unique name that Acoustic Exchange can use to identify the source endpoint.

B: Identify the destination segment

Property	Use	Data type	Valid value	Description
`destination EndpointID`	Required	Long	Specified by destination endpoint	Define a unique value that Acoustic Exchange can use to identify the destination endpoint.
`destination SegmentName`	Optional	String	Specified by destination endpoint	Define a unique name that Acoustic Exchange can use to identify the source endpoint. Acoustic Exchange uses the name to display and identify the audience data in the Acoustic Exchange user interface. If nothing is entered, Acoustic Exchange generates a segment name. Enter the name of an existing segment to pull data from that segment.
`destinationSegmentDescription`	Optional	String	Specified by destination endpoint	Define a brief description that Acoustic Exchange can use to identify the source endpoint. Acoustic Exchange uses the description to describe the audience data in the Acoustic Exchange user interface.
`destinationSegmentID`	Optional	String	<Text>	If you are working with an existing segment, enter its segment ID. If this field is not present, Acoustic Exchange creates a new segment. Note: `action` must be specified when you are working with an existing segment.
`exportCategory`	Optional	String	Specified by destination endpoint

C: Specify the action of the call

Property	Use	Data type	Valid value	Description
`action`	Optional	String	`add` `replace` `remove`	Indicate whether the call adds, replaces, or removes an audience. Specifying the action is optional if you are working with a new segment. It is required if you are working with an existing segment.

Property

Use

Data type

Valid value

Description

action

Optional

String

add

replace

remove

Indicate whether the call adds, replaces, or removes an audience. Specifying the action is
optional if you are working with a new segment. It is required if you are working with an existing segment.

D: Specify identity and attribute mapping

Property	Use	Data type	Valid value	Description
`sourceIdentifiers`	Required	JSON object	Specified by the source endpoint	In this JSON array, indicate the source identifiers of the source segment that are to be mapped to a single destination identifier of the destination segment. You can map multiple source identifiers to a single destination identifier.
`destination Identifier`	Required	JSON object	Specified by the destination endpoint	In this JSON object, indicate the destination identifier that you are mapping the source identifiers to. Multiple source identifiers can be mapped to a single destination identifier.
`attributeMappings`	Optional	JSON object	Specified by both endpoints	If source and destination endpoints both support extra columns for attributes, indicate how to convert each attribute in the source segment to a corresponding attribute in the destination segment.

Property

Use

Data type

Valid value

Description

sourceIdentifiers

Required

JSON object

Specified by the source endpoint

In this JSON array, indicate the source identifiers of the source segment that are to be mapped to a single destination identifier of the destination segment.

You can map multiple source identifiers to a single destination identifier.

destination Identifier

Required

JSON object

Specified by the destination endpoint

In this JSON object, indicate the destination identifier that you are mapping the source
identifiers to.

Multiple source identifiers can be mapped to a single destination
identifier.

attributeMappings

Optional

JSON object

Specified by both endpoints

If source and destination endpoints both support extra columns for attributes, indicate how to convert each attribute in the source segment to a corresponding attribute in the destination segment.

E: Indicate whether the Acoustic Exchange Identity Store is to be updated

Property	Use	Data Type	Valid value	Description
`updateIdentities`	Required	Boolean	`true\|false`	If this value is set to true, the call uploads identity data from the specified endpoint to the Acoustic Exchange Identity Store. It also appears in the job payload when you get job details. If this value is set to false, the call reads from the Acoustic Exchange Identity Store and does not write to it.

Property

Use

Data Type

Valid value

Description

updateIdentities

Required

Boolean

true|false

If this value is set to true, the call uploads identity data from the specified endpoint to the Acoustic Exchange Identity Store. It also appears in the job payload when you get job details.

If this value is set to false, the call reads from the Acoustic Exchange Identity Store and does not write to
it.

F: Set minimum number of records

Property	Use	Data type	Valid value	Description
`minCount`	Optional	Integer	<integer>	The `minCount` is the minimum number of records that are sent to the destination endpoint. If the number of converted records is less than this number, the scheduled job cancels. By default, the number is 1.

G: Schedule audience sharing

Property	Use	Data type	Valid value	Description
`runNow`	Optional	Boolean	`true\|false`	Indicate whether you would like to initiate the audience share from a source endpoint to a destination endpoint. Note: If set to `true` the `startDate` and `startTime` are ignored and the job runs immediately.
`runRepeat`	Optional	Boolean	`true\|false`	Indicate whether the audience share must repeat.
`daysOfWeek`	Optional	String	`1-7` Day of the week: `1` Weekly:`1` Days of the week: `1,3,5` Daily: `null` Monthly: `null`	Indicate the day or days of the week share the audience from the source endpoint to the destination endpoint. In this field 1-7 is equivalent to SUN-SAT
`daysOfMonth`	Optional	String	`1-31` Days of the month: `1,3-5,10` One time: `1` Monthly: `1` Daily: `*` Weekly: `null`	Indicate the day or days of the month to share the audience from the source endpoint to the destination endpoint.
`monthsOfYear`	Optional	String	`1-12` Days of the month: `1,3,4` One time: `1` Monthly: `*` Daily: `null` Weekly: `null`	Indicate the month or months of the year to share the audience from the source endpoint to the destination endpoint.
`year`	Optional	String	<year>	Indicate the year to share the audience from the source endpoint to the destination endpoint.
`startHour`	Optional	String	`1-24`	Indicate the hour for the audience share to start.
`startMinute`	Optional	String	`01-59`	Indicate the minute for the audience share to start.
`startSecond`	Optional	String	`01-59`	Indicate the second for the audience share to start.
`startDate`	Optional	String	`MM/dd/yyyy`	Indicate the start or one time run date for the audience share.
`endDate`	Optional	String	`MM/dd/yyyy`	Indicate the date for the audience share to end.
`timeSliceStartDate`	Optional	String	`MM/dd/yyyy`	A `timeSlice` is used to pull record from a specific length of time, instead of pulling records from all time for an audience share. For example, by indicating the `timeSliceStartDate` as `09/27/2016` and the `timeSliceEndDate` as `09/28/2016`, records for those two days are pulled for an audience share. Indicate the `timeSliceStartDate` .
`timeSliceEndDate`	Optional	String	`MM/dd/yyyy`	Indicate the `timeSliceEndDate`.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

POST /v1/jobs/segmentExport provides responses as follows.

Code	Description
200 – 299	Success. Acoustic Exchange returns the job ID of the segment export job that is created in Acoustic Exchange. If you created the job for use with a segment producer that pushes data to Acoustic Exchange, Acoustic Exchange creates the job and leaves it in WAITING_TO_RECEIVE_DATA state, pending a call by the Acoustic Exchange user interface or another API.
400 – 499	There is a problem with the API request. Examine the request for errors.
500 – 599	System error. Contact Acoustic Exchange Support for assistance.

What to do next

If the source endpoint is a PUSH audience provider, you can call POST /v1/jobs/{jobId}/data to upload a segment to the export job that Acoustic Exchange holds in WAITING_TO_RECIEVE_DATA state.

If the destination endpoint is a PULL audience consumer, you can call GET /v1/jobs/{jobId}/segmentDataFiles/{fileName} to download audience data.

Specify the job ID that POST /v1/jobs/segmentExport returns.

POST /v1/jobs/identityImport

Use this API to schedule a bulk upload of segmented identity data to the Acoustic Exchange Identity Store.

About this API

In most cases, Acoustic Exchange gathers identity data by examining events that are produced and consumed by endpoints. As such, it can take new Acoustic Exchange endpoints that use this process some time to build a large repository of identity data within the Acoustic Exchange Identity Store. However, if your endpoint already has a repository of identity data, you can upload that data in bulk to the Acoustic Exchange Identity Store by using the POST /v1/jobs/identityImport API.

The response that this API provides depends on the producer type of the source endpoint.

If the source endpoint is a PULL segment producer, the API call initiates the identity data upload and returns a generated job ID. Additionally, it schedules a new job to check the endpoint’s export data job status. As a result, Acoustic Exchange periodically checks the jobs status until it reads as complete and the identity data is uploaded.
If the source endpoint is a PUSH audience provider: Acoustic Exchange creates the export job but waits for the source endpoint to upload audience data. Acoustic Exchange puts the job in WAITING_TO_RECIEVE_DATA status. To continue the audience sharing process, the source endpoint must call POST /v1/jobs/{jobId}/data to upload the audience data to Acoustic Exchange.

Request

You must use an account-level authentication key as the authorization bearer in the API call.

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

Note: If the audience segment has a string segment ID, then the property segmentIDString should be defined in place of the property segmentID.

Example request (as a curl command):

curl -v 
  -X PUT
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -d '{
        "endpointID":<source endpoint ID>,
        "segmentID":<source segment ID>|"segmentIDString":<string segment ID (source)>,
        "databaseID":<source database ID>
        "sourceIdentifiers":["<identifier name>, <identifier name>"]
        "scheduleDetails":{
        "runNow":true|false,
        "runRepeat":true|false,
        "daysOfWeek":<day of the week>,
        "daysOfMonth":<day of the month>,
        "monthsOfYear":<months of the year>,
        "year":<the year>,
        "startHour":"<the hour to start>",
        "startMinute":"<the minute to start>",
        "startSecond":"<the second to start>",
        "startDate":"<the start date>",
        "endDate":<the end date>,
        "timeSliceStartDate":<date>,
        "timeSliceEndDate":<date>},
       }'
     <base URL>/v1/jobs/identityImport

The following table describes the JSON payload of the call.

JSON

JSON	Requirements
`{ "endpointID":<endpoint ID (source)>, "segmentID":<segment ID (source)>\|"segmentIDString":<string segment ID (source)>, "databaseID":<source database ID>`	A. Identify the source segment.
`"sourceIdentifiers":["<identifier name>, <identifier name>"]`	B. Specify source identifiers.
`"scheduleDetails":{ "runNow":true\|false, "runRepeat":true\|false, "daysOfWeek":<day of the week>, "daysOfMonth":<day of the month>, "monthsOfYear":<months of the year>, "year":<the year>, "startHour":"<the hour to start>", "startMinute":"<the minute to start>", "startSecond":"<the second to start>", "startDate":"<the start date>", "endDate":<the end date>, "timeSliceStartDate":<date>, "timeSliceEndDate":<date> },`	C. Schedule the identity data upload.

Requirements

{
  "endpointID":<endpoint ID (source)>,
  "segmentID":<segment ID (source)>|"segmentIDString":<string segment ID (source)>,
  "databaseID":<source database ID>

Identify the source segment.

"sourceIdentifiers":["<identifier name>, <identifier name>"]

Specify source identifiers.

"scheduleDetails":{
        "runNow":true|false,
        "runRepeat":true|false,
        "daysOfWeek":<day of the week>,
        "daysOfMonth":<day of the month>,
        "monthsOfYear":<months of the year>,
        "year":<the year>,
        "startHour":"<the hour to start>",
        "startMinute":"<the minute to start>",
        "startSecond":"<the second to start>",
        "startDate":"<the start date>",
        "endDate":<the end date>,
        "timeSliceStartDate":<date>,
        "timeSliceEndDate":<date>
    },

Schedule the identity data upload.

A: Identify the source segment

Property	Use	Data type	Valid value	Description
`endpointID`	Required	Long	Specified by source endpoint	Define a unique value that Acoustic Exchange can use to identify the source endpoint.
`segmentID`	Required If segment ID is not a string	Long	Specified by source endpoint	Define a unique value that Acoustic Exchange can use to identify the source segment.
`segmentIDString`	Required If segment ID is a string	String	Specified by source endpoint	Define a unique value that Acoustic Exchange can use to identify the source segment. Note: Define this property only if the source segment ID is a string.
`databaseID`	Optional	String	Specified by source endpoint	Define a unique value that Acoustic Exchange can use to identify the source database.

B: Specify identity and attribute mapping

Property	Use	Data type	Valid value	Description
`sourceIdentifiers`	Optional	JSON object	Specified by the source endpoint.	In this JSON array, indicate the source identifiers of the source segment that are to be mapped to a single destination identifier of the destination segment. You can map multiple source identifiers to a single destination identifier.

Property

Use

Data type

Valid value

Description

sourceIdentifiers

Optional

JSON object

Specified by the source endpoint.

In this JSON array, indicate the source identifiers of the source segment that are to be mapped to a single destination identifier of the destination segment.

You can map multiple source identifiers to a single destination identifier.

C: Schedule the identity data upload

Property	Use	Data type	Valid value	Description
`runNow`	Optional	Boolean	`true\|false`	Indicate whether you would like to initiate the audience share from a source endpoint to a destination endpoint. Note: If set to `true` the `startDate` and `startTime` are ignored and the job runs immediately.
`runRepeat`	Optional	Boolean	`true\|false`	Indicate whether the audience share must repeat.
`daysOfWeek`	Optional	String	`1-7` Day of the week: `1` Weekly:`1` Days of the week: `1,3,5` Daily: `null` Monthly: `null`	Indicate the day or days of the week share the audience from the source endpoint to the destination endpoint. In this field 1-7 is equivalent to SUN-SAT
`daysOfMonth`	Optional	String	`1-31` Days of the month: `1,3-5,10` One time: `1` Monthly: `1` Daily: `*` Weekly: `null`	Indicate the day or days of the month to share the audience from the source endpoint to the destination endpoint.
`monthsOfYear`	Optional	String	`1-12` Days of the month: `1,3,4` One time: `1` Monthly: `*` Daily: `null` Weekly: `null`	Indicate the month or months of the year to share the audience from the source endpoint to the destination endpoint.
`year`	Optional	String	<year>	Indicate the year to share the audience from the source endpoint to the destination endpoint.
`startHour`	Optional	String	`1-24`	Indicate the hour for the audience share to start.
`startMinute`	Optional	String	`01-59`	Indicate the minute for the audience share to start.
`startSecond`	Optional	String	`01-59`	Indicate the second for the audience share to start.
`startDate`	Optional	String	`MM/dd/yyyy`	Indicate the start or one time run date for the audience share.
`endDate`	Optional	String	`MM/dd/yyyy`	Indicate the date for the audience share to end.
`timeSliceStartDate`	Optional	String	`MM/dd/yyyy`	A `timeSlice` is used to pull record from a specific length of time, instead of pulling records from all time for an audience share. For example, by indicating the `timeSliceStartDate` as `09/27/2016` and the `timeSliceEndDate` as `09/28/2016`, records for those two days are pulled for an audience share. Indicate the `timeSliceStartDate` .
`timeSliceEndDate`	Optional	String	`MM/dd/yyyy`	Indicate the `timeSliceEndDate`.

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

POST /v1/jobs/identityImport provides responses as follows.

Code	Description
200 – 299	Success. Acoustic Exchange has successfully uploaded the segmented identity data to the Acoustic Exchange Identity Store and returns the generated job ID.
400 – 499	There is a problem with the API request. Examine the request for errors.
500 – 599	System error. Contact Acoustic Exchange Support for assistance.

GET /v1/endpoint

About this API

Request

Response

DELETE /v1/endpoint/{endpointId}

About this API

Request

PUT /v1/endpoint/{endpointId}

About this API

Request

PUT /v1/endpoint/database

About this API

Request

Response

PUT /v1/endpoint/disable/{endpointId}

Before you begin

About this API

Request

Response

PUT /v1/endpoint/enable/{endpointId}

Before you begin

About this API

Request

Response

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

About this API

Request

Response

A: Attributes

B: Segment identification

POST /v1/jobs/segmentExport

About this API

Request

A: Identify the source segment

B: Identify the destination segment

C: Specify the action of the call

D: Specify identity and attribute mapping

E: Indicate whether the Acoustic Exchange Identity Store is to be updated

F: Set minimum number of records

G: Schedule audience sharing

Response

What to do next

POST /v1/jobs/identityImport

About this API

Request

A: Identify the source segment

B: Specify identity and attribute mapping

C: Schedule the identity data upload

Response

Join The Discussion Cancel reply