Marketers define audiences by segmenting their customer databases to identify and select groups of individuals that share one or more specified characteristics.
Implementing the segment API in your business solution or product enables
Segment API implementation for Pull-type audience producers
Audience producer endpoints can implement the following
GET v1/segments
Returns a list of audiences (segments) that are available on an audience producer or audience consumer endpoint.
GET v1/segments/{segmentId}
Returns details about a specific source audience or destination audience.
GET v1/segments/{segmentId}/data
Requests immediate upload of available data to Acoustic Exchange. If no data is available, Acoustic Exchange requests that you create a data upload job.
POST v1/jobs
Requests that you create a job to upload audience data when it becomes available.
GET v1/jobs/{jobId}
Polls for job status. Continues to poll when data upload begins and until the upload
completes.
GET
v1/jobs/{jobId}/data/{jobDataId}
Returns the requested audience.
Segment API implementation for Push-type audience consumers
When
The audience share actions that an endpoint provides is determined by the share actions that are configured during endpoint registration. You must implement the segment APIs on an audience consumer endpoint to support the audience sharing options that are configured for your endpoint as an audience destination.
Audience consumer endpoints can implement the following
GET v1/segments
Returns a list of audiences that are already available as a destination audience and that can receive additional audience data or be modified.
GET v1/segments/{segmentId}
Returns additional data about a specific destination audience.
POST v1/segments
Creates a new audience on the destination endpoint.
POST v1/segments/{segmentId}/data
Adds audience data to the specified audience, either a new audience or existing
audience.
PUT v1/segments/{segmentId}/data
Replaces all existing data in the specified audience with new audience data.
DELETE /v1/segments/{segmentId}/data
Deletes specific records in the specified audience.
GET /v1/segments
About this API
You can implement this API for endpoints that are either an audience producer or audience consumer. If your application is an audience producer and consumer, you need to implement this API only once and you can use the same URL for both.
When
The responses must include an audience name, a unique ID, and an audience type. The audience ID, also referred to as a segment ID, is used to identify the audience in other calls to v1/segments. The audience type must be one of the types that
For audience producer endpoints,
-Contact Lists
-Databases
-Queries
For audience consumer endpoints,
For either producer or consumer endpoints, if the response does not specify the audience type in the API call,
Request
The following example illustrates a request (using curl) to retrieve a list of available audiences:
curl -v
-X GET
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: application/json; charset=utf-8”
https://<endpoint URL>/v1/segments
curl -v
-X GET
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: application/json; charset=utf-8”
https://<endpoint URL>/v1/segments
The endpoint URL is the URL that you establish to receive API calls for your
Response
A successful response includes a JSON payload that lists available audiences, including audience name, a unique ID, and an audience type.
The response from audience producer endpoints can specify type as a database, a contact list, or as a query. See the following example response from an audience producer endpoint.
{
"responseStatus": "success",
"result": {
"totalCount": 4,
"list": [
{
"id": 1,
"name": "EmailMarketingData",
"type": "Databases"
},
{
"id": 2,
"name": "Last weeks abandoned carts",
"type": "Contact Lists"
},
{
"id": 3,
"name": "LatestOptOuts",
"type": "Queries"
},
{
"id": 4,
"name": "HashedEmailData",
"type": "Contact Lists"
}
]
}
}
The JSON payload that is returned from an audience consumer endpoint must describe existing audiences on the destination endpoint that can accept new audience data or that can be modified by calls from Acoustic Exchange. The response from audience consumers specifies audience type
only as Contact Lists. See the following example response from an audience consumer endpoint.
{
"responseStatus": "success",
"result": {
"totalCount": 2,
"list": [
{
"id": 1,
"name": "All abandoned carts",
"type": "Contact Lists"
},
{
"id": 2,
"name": " All Opt Outs ",
"type": "Contact Lists"
}
]
}
}
What to do next
The
GET /v1/segments/{segmentId}
This API returns details about a specific source or destination audience.
About this API
Through the Audiences tab,
In the URL for the request for additional information about an audience,
Request
The following example illustrates a request (using curl) to retrieve information about an audience.
curl -v
-X GET
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: application/json; charset=utf-8”
https://<endpoint URL>/v1/segments/{segmentId}
The endpoint URL is the URL that you establish to receive API calls for your
Response
The JSON payload that is returned from an audience producer endpoint must identify the audience by segment ID and by name. It must also list the audience attributes that the audience can provide.
The following example illustrates a typical response. Responses from audience producer endpoints and audience consumer endpoints return the same JSON structure.
{
"responseStatus": "success",
"result": {
"id": 1,
"name": "EmailMarketingData",
"segmentAttributes": [
{
"name": "Email"
},
{
"name": "FirstName"
},
{
"name": "LastName"
},
{
"name": "Sex"
}
]
}
}
What to do next
Upon request from
GET /v1/segments/{segmentId}/data
About this API
If the data is available at the time of the request (synchronous), then the response includes the data. If the data is not available (asynchronous), then the call must return error 501, to indicate that
Request
The following example illustrates a request (using curl) to return data from an audience.
curl -v
-X GET
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: text/csv; charset=utf-8”
https://<endpoint URL>/v1/segments/{segmentId}/data
The endpoint URL is the URL that you establish to receive API calls for your
Response
If data is available for the specified audience, return 200 and a comma-separated list of audience values. The first row of the response must identify the field names.
Email,FirstName,LastName,Sex
[email protected],Irene,Ferguson,F
[email protected],Jimmy,Cox,M
[email protected],Pamela,Williams,F
[email protected],Jerry,Campbell,M
[email protected],Howard,Bennett,M
If data is not available in the specified audience, return error code “501”.
What to do next
If data is not immediately available,
POST /v1/jobs
About this API
The response must identify the job that provides the data (jobId) and identify the audience (jobDataId).
Request
The following example illustrates a request (using curl) to create a job to return data from an audience source endpoint.
curl -v
-X POST
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: application/json; charset=utf-8”
-d '{"segmentID":<segment ID>,"jobType":"ExportSegmentData"}'
https://<endpoint URL>/v1/jobs
The endpoint URL is the URL that you establish to receive API calls for your
{
"segmentId": 1,
"jobType": "ExportSegmentData"
}
segmentId
Required
String
Segment ID
The request provides the segment ID that is specified in a GET call to v1/segments/{segmentId}/data to identify the audience that provides audience data.
jobType
Required
String
ExportSegment Data
The name of the job must be "ExportSegmentData".
Response
A successful response returns a success code and includes a JSON payload that includes values that
{
"responseStatus": "success",
"result": {
"jobId": 9336,
"jobDataId": 652
}
}
responseStatus
Required
String
Success
Indicates whether the job was created.
jobId
Required
String
Unique job ID
Provide the ID that
jobDataId
Required
String
Any value that the source endpoint can use to identify the audience.
Provide a value that
The values for jobId and jobDataId are specified in subsequent API calls to the audience source endpoint.
What to do next
completion of an upload in progress.
GET /v1/jobs/{jobId}
Before you begin
About this API
Request
The following example illustrates a request (using curl) to get the current status of a job that is specified by its job ID, which is specified as a URL parameter.
curl -v
-X GET
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: application/json; charset=utf-8”
https://<endpoint URL>/v1/jobs/{jobId}
The endpoint URL is the URL that you establish to receive API calls for your
Response
A successful response returns a success code and includes a JSON payload that specifies the job ID and the status of the job. The response JSON must be structured as shown in the example.
{
"responseStatus": "success",
"result": {
"id": 9127,
"status": "complete"
}
}
responseStatus
Required
String
id
String
Job ID
The system defined identifier that is assigned to the job by a POST call to /v1/jobs.
status
String
- complete
- error
- canceled
- running
- waiting
- unknown
Indicates the current status of the job.
What to do next
After the job completes successfully,
GET /v1/jobs/{jobId}/data/{jobDataId}
Before you begin
About this API
The call to this API must specify the value for jobId and jobDataId that were generated by calling POST v1/jobs on the source endpoint. A successful response to this API call returns audience data as a comma-separated list.
Request
The following example illustrates a request (using curl) to return audience data that was prepared by a job. The request parameters must include values that identify the audience and the job.
curl -v
-X GET
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: application/json; charset=utf-8 “
https://<endpoint URL>/v1/jobs/{jobId}/data/{jobDataId}
The endpoint URL is the URL that you establish to receive API calls for your
Response
A successful response returns 200 success code and a comma-separated list of audience values. The first row of the response must identify the field names.
Email,FirstName,LastName,Sex
[email protected],Irene,Ferguson,F
[email protected],Jimmy,Cox,M
[email protected],Pamela,Williams,F
[email protected],Jerry,Campbell,M
[email protected],Howard,Bennett,M
POST /v1/segments
About this API
Request
The following example illustrates a request (using curl) to create a new audience on a destination endpoint.
curl -v
-X POST
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: application/json; charset=utf-8”
https://<endpoint URL>/v1/segments
The endpoint URL is the URL that you establish to receive API calls for your
The request includes a JSON payload that provides an audience name and description. The request can also specify a category.
{
"name": "OptInThisWeek",
"description": "New curent subscriptions",
"category": "consent"
}
name
Required
String
User defined
Name of the new audience as the Acoustic Exchange user enters it through the Acoustic Exchange user interface.
description
Required
String
User defined
Description of the new audience.
category
Required
String
User defined
Additional information that is specified by
note field in
Response
A successful response returns a success code and includes a JSON payload that specifies the segment ID of the new audience. The response JSON must be structured as shown in the example.
{
"responseStatus": "success",
"result": {
"segmentId": "<segmentId>"
}
}
What to do next
When
POST /v1/segments/{segmentId}/data
About this API
Request
The following example illustrates a request (using curl) to add audience data to a new or existing audience on a destination endpoint.
curl -v
-X POST
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: text/csv; charset=utf-8”
-d "email,firstName,[email protected],jane,smith"
https://<endpoint URL>/v1/segments/{segmentId}/data?
totalBatchCount={number}¤tBatchNumber={number}&
shareAction=ADD&category={note}&ids={identifier}&
sourceEndpointID={identifier}&sourceSegmentID={identifier}
The request parameters include values that identify the audience and the job, as described in the
table.
totalBatch Count
Optional
string
Number
Total number of batches to be sent to the audience destination endpoint.
currentBatch Number
Optional
string
Number
Current batch count being sent to the consumer. Each batch can contain a maximum of 10,000 records. If the share is larger,
shareAction
Optional
string
ADD
How audience records are modified during audience sharing. Add: the new records are added to any existing records.
category
Optional
string
Text
Descriptive information that the user entered in the Add a note field during audience sharing.
ids
Optional
string
Identifier
The identifier that the Acoustic Exchange user specified during audience sharing.
sourceEndpointID
Optional
string
Endpoint ID
The ID of the source endpoint that provided the audience data.
sourceSegmentID
Optional
string
Audience ID
The ID of the source audience from which the audience data originated.
Acoustic Exchange includes an endpoint-level authentication key as the authorization bearer.
The endpoint URL is the URL that you establish to receive API calls for your Acoustic Exchange endpoint.
The POST includes the audience data to be added to the destination audience. The call adds the data as a comma-separated list of audience values, as illustrated in the example below. The first row of the response payload identifies the field names.
EmailAddress,First,Last,Gender
[email protected],Tina,Jones,F
[email protected],James,Cox,M
[email protected],Joan,Williams,F
[email protected],John,Smith,M
Response
A successful response returns a success code and includes a JSON payload that specifies the segment ID of the updated audience, the number of records that were received, the number of records that are considered not valid, and the number of new records that are created in the destination audience. The response JSON must be structured as shown in the example.
{
"responseStatus": "success",
"result": {
"segmentId": "259",
"numReceived": "4",
"numInvalid": "0",
"numAdded": "4"
}
}
segmentId
Required
String
Segment ID
The unique segment ID that identifies the source of the audience data.
numReceived
Optional
Number
Number
Number of records received.
numInvalid
Optional
Number
Number
The number of audience records that were not valid records.
numAdded
Optional
Number
Number
Number of records that are added to the destination audience.
PUT /v1/segments/{segmentId}/data
Acoustic Exchange calls this API on an audience destination endpoint to replace audience data that is present in a specified audience.
About this API
Acoustic Exchange calls this API when Acoustic Exchange users select the option to replace all records in the destination audience when they share audiences between endpoints. Acoustic Exchange provides the audience data as a list of comma-separated values (.csv).
Request
The request must specify the segment ID of the audience where you want to replace audience data. Call GET v1/segments on the destination endpoint to get a list of available audiences.
The following example illustrates a request (using curl) to replace audience data in an existing audience on a destination endpoint.
curl -v
-X PUT
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: text/csv; charset=utf-8”
-d "email,firstName,[email protected],jane,smith"
https://<endpoint URL>/v1/segments/{segmentId}/data?
totalBatchCount={number}¤tBatchNumber={number}&
shareAction=REPLACE&category={note}&ids={identifier}&
sourceEndpointID={identifier}&sourceSegmentID={identifier}
The request parameters include values that identify the audience and the job, as described in the table.
totalBatch Count
Optional
string
Number
Total number of batches to be sent to the audience destination endpoint.
current Batch number
Optional
string
Number
Current batch count being sent to the consumer Each batch can contain a maximum of 10,000 records. If the share is larger,
shareAction
Optional
string
REPLACE
How audience records are modified during audience sharing. Replace: the new records replace all existing records.
category
Optional
string
Text
Descriptive information that the user entered in the Add a note field during audience sharing.
ids
Optional
string
Identifier
The identifier that the
sourceEndpointID
Optional
string
Endpoint ID
The ID of the source endpoint that provided the audience data.
sourceSegmentID
Optional
string
Audience ID
The ID of the source audience from which the audience data originated.
The endpoint URL is the URL that you establish to receive API calls for your
The request includes the audience data that replaces the existing data in the destination audience. The call adds the new data as a comma-separated list of audience values, as illustrated in the example below. The first row of the response payload identifies the field names.
{
"responseStatus": "success",
"result": {
"segmentId": "259",
"numReceived": "1",
"numInvalid": "0",
"numAdded": "1"
}
}
segmentId
Required
String
Segment ID
The segment ID of the destination audience.
numReceived
Optional
Number
Number
Number of records received.
numInvalid
Optional
Number
Number
The number of audience records that were not valid records.
numAdded
Optional
Number
Number
Number of records that are added to the destination audience.
DELETE /v1/segments/{segmentId}/data
About this API
Request
The following example illustrates a request (using curl) to remove audience data from an existing audience on a destination endpoint.
curl -v
-X DELETE
-H "Authorization: Bearer <endpoint-level authentication key>"
-H "Content-Type: text/csv; charset=utf-8”
-d "email,firstName,[email protected],jane,smith"
https://<endpoint URL>/v1/segments/{segmentId}/data?
totalBatchCount={<number>}¤tBatchNumber={<number>}&
shareAction=REMOVE&category={"<note>"}&ids={identifier}&
sourceEndpointID={identifier}&sourceSegmentID={identifier}
The request parameters include values that identify the audience and the job, as described in the table.
totalBatch Count
Optional
String
Number
The request parameters include values that identify the audience and the job, as described in the table.
currentBatch Number
Optional
String
Number
Current batch count being sent to the consumer Each batch can contain a maximum of 10,000 records. If the share is larger,
shareAction
Optional
String
REMOVE
How audience records are modified during audience sharing. Remove: the specified records are removed from the destination audience.
category
Optional
String
Text
Descriptive information that the user entered in the Add a note field during audience sharing.
ids
Optional
String
Identifier
The identifier that the
sourceEndpointID
Optional
String
Endpoint ID
The ID of the source endpoint that provided the audience data.
sourceSegmentID
Optional
String
Audience ID
The ID of the source audience from which the audience data originated.
The endpoint URL is the URL that you establish to receive API calls for your
If the DELETE call replaces specific audience records, the call includes the audience data that must be removed from the existing audience in the destination audience. The call identifies data to be removed in a comma-separated list of audience values, as illustrated in the example below. The first row of the response payload identifies the field names.
EmailAddress,First,Last,Gender
[email protected],Tina,Jones,F
[email protected],James,Cox,M
[email protected],Joan,Williams,F
[email protected],John,Smith,M
Response
A successful response returns a success code and includes a JSON payload that specifies the segment ID of the updated audience, the number of records that were processed, the number of records that are considered not valid, and the number of records that were removed. The response JSON must be structured as shown in the example.
{
"responseStatus": "success",
"result": {
"segmentId": "259",
"numReceived": "1",
"numInvalid": "0",
"numRemoved": "1"
}
}
segmentID
Required
String
Segment ID
The segment ID of the destination audience.
numReceived
Required
Number
System defined
The number of records that are included in the delete request.
numInvalid
Number
System defined
The number of audience that were not valid records.
numRemoved
Optional
Number
System defined
The number of new records that were removed from the destination audience.
Updated 9 months ago