Segment API

Suggest Edits

endpoint providers implement the segment API to create and manage audiences that users share through . By implementing the segment API in their business solution or product, endpoint providers can programmatically identify specific audiences and control how they are exchanged through .

Marketers define audiences by segmenting their customer databases to identify and select groups of individuals that share one or more specified characteristics. uses the term audience to refer to the segments that result from database segmentation.

Implementing the segment API in your business solution or product enables to find audiences, get information about the audiences, and share audiences through . Endpoints that produce audiences must implement the segment API differently from endpoints that consume audiences.

provides Test Drive as a separate application that you can use to help you to implement the segment APIs. Test Drive lets you perform and examine the response to each request in isolation to help you implement these APIs with your business solution or product.

Segment API implementation for Pull-type audience producers

Audience producer endpoints can implement the following segment APIs so that can call them in response to user requests.

API

Function

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 users send audience data to an endpoint, supports giving users the option to create a new destination audience, replace all data in an existing audience, add data to an existing audience, or remove specific records from an existing audience.

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 segment APIs, so that can call them in response to user requests.

API

Function

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

calls this API to get a list of audiences (segments) that are defined on an endpoint. uses the API response to display the available audience sources and destinations in the user interface.

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 makes a GET call to v1/segments segments to an audience producer, the response must return a list of audiences that can provide audience data. Calls to audience consumer endpoints must return a list of audiences that can receive new audience data or that already contain audience data and can be updated.

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 supports. The user interface displays only supported audience types.

For audience producer endpoints, supports and displays the following audience (segment) types.

-Contact Lists
-Databases
-Queries

For audience consumer endpoints, supports and displays only audiences with the type Contact Lists.

For either producer or consumer endpoints, if the response does not specify the audience type in the API call, sets the type to contact lists.

Request

The following example illustrates a request (using curl) to retrieve a list of available audiences:

cURL

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

curl -v 
-X GET 
-H "Authorization: Bearer <endpoint-level authentication key>" 
-H "Content-Type: application/json; charset=utf-8” 
https://<endpoint URL>/v1/segments

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 endpoint. Call the API with an empty request body.

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.

JSON

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

JSON

{
    "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 user interface provides an option to display additional descriptive information. To display additional audience information to users, uses the value for “id” that this call returns as input in a GET call to v1/segments/{segmentId}.

GET /v1/segments/{segmentId}

This API returns details about a specific source or destination audience. displays the additional information in the user interface. Implement this API on endpoints that are either an audience producer or audience consumer.

About this API

Through the Audiences tab, users can request details about each source or destination audience. calls this API to provide the additional information to users to help them determine which audience to share. The response to the call must provide the name of the audience and a list of attributes that the audience provides.

In the URL for the request for additional information about an audience, includes the corresponding segment ID returned by GET v1/segments as the value for segmentId. You need to implement this API only once if your application is an audience producer and consumer and you use the same URL for both.

Request

The following example illustrates a request (using curl) to retrieve information about an audience.

cURL

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}

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 endpoint. calls the API with an empty request body.

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.

JSON

{
    "responseStatus": "success",
    "result": {
        "id": 1,
        "name": "EmailMarketingData",
        "segmentAttributes": [
            {
                "name": "Email"
            },
            {
                "name": "FirstName"
            },
            {
                "name": "LastName"
            },
            {
                "name": "Sex"
            }
        ]
    }
}

What to do next

Upon request from users, get an audience from an audience source endpoint. Sharing the audience data requires a series of calls by to the segment API that you implement.

GET /v1/segments/{segmentId}/data

calls this API to request an immediate return of available data to . If no data is available, requests that the endpoint create a job to prepare data that becomes available later.

About this API

calls this API as implemented on an audience source endpoint to return audience data from the endpoint to .

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 must request a job to return the audience data.

Request

The following example illustrates a request (using curl) to return data from an audience. specifies the audience by passing the unique segment ID that identifies the audience.

cURL

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

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 endpoint. calls this API with an empty request body.

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.

Text

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, requests that the endpoint create a job to provide the audience data later. requests the job with a POST call to v1/jobs.

POST /v1/jobs

makes this API call to request that an endpoint create a job to return audience data when it becomes available.

About this API

calls this API on an audience source endpoint to request that the endpoint create a job to provide the audience data asynchronously.

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

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

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 endpoint. The request includes a JSON payload as shown in the following example.

JSON

{
    "segmentId": 1,
    "jobType": "ExportSegmentData"
 }

Property

Use

Data type

Valid value

Description

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 can use to specify the job and audience that contain the required audience data. The response JSON must be structured as shown in the example.

JSON

{
    "responseStatus": "success",
    "result": {
        "jobId": 9336,
        "jobDataId": 652
    }
}

Property

Use

Data type

Valid value

Description

responseStatus

Required

String

Success

Indicates whether the job was created.

jobId

Required

String

Unique job ID

Provide the ID that can us to specify the job that returns an audience asynchronously.

jobDataId

Required

String

Any value that the source endpoint can use to identify the audience.

Provide a value that can specify in a subsequent call to identify to the source endpoint which audience to return.

The values for jobId and jobDataId are specified in subsequent API calls to the audience source endpoint.

What to do next

polls the source endpoint to check on the availability of fresh audience data or the
completion of an upload in progress.

GET /v1/jobs/{jobId}

calls this API on the audience source endpoint to request the current job status.

Before you begin

calls POST v1/jobs to generate a job ID.

About this API

calls this API periodically to poll the source endpoint for the current job status. When the job begins to upload audience data, continues to poll until the upload completes.

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

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}

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 endpoint. calls this API with an empty request body. It uses the job ID that was specified by a previous POST call to v1/jobs to set the value for jobId in the request URL.

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.

JSON

{
    "responseStatus": "success",
    "result": {
        "id": 9127,
        "status": "complete"  
    }
}

Property

Use

Data type

Valid value

Description

responseStatus

Required

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, calls the audience source endpoint to upload the audience data.

GET /v1/jobs/{jobId}/data/{jobDataId}

calls this API on an audience source endpoint to return audience data after a job to prepare the data completes .

Before you begin

calls GET v1/jobs/{jobId} to ensure that audience data is ready for return to .

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

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}

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 endpoint. calls this API with an empty request body. The request must include parameters that specify the values for jobId and jobDataId that were generated by an earlier call to POST v1/jobs.

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.

Text

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

calls this API on an audience destination endpoint to create a new audience on the endpoint.

About this API

calls this API to create a new, empty segment in the destination endpoint. The response includes the segmentId of the new segment. You include this segmentId in subsequent API calls for the new segment.

Request

The following example illustrates a request (using curl) to create a new audience on a destination endpoint.

cURL

curl -v 
-X POST 
-H "Authorization: Bearer <endpoint-level authentication key>" 
-H "Content-Type: application/json; charset=utf-8”
https://<endpoint URL>/v1/segments

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

The request includes a JSON payload that provides an audience name and description. The request can also specify a category. structures the JSON payload as shown in the following example.

JSON

{
    "name": "OptInThisWeek",
    "description": "New curent subscriptions",    
    "category": "consent"  
}

Property

Use

Data type

Valid value

Description

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 users in the Add a
note field in when the user shares an audience.

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.

JSON

{
    "responseStatus": "success",
    "result": {
        "segmentId": "<segmentId>"
    }
}

What to do next

When creates a new audience, the only option is to add members to the new audience. calls POST v1/segments/{segmentId}/data to add data to the newly created destination audience.

POST /v1/segments/{segmentId}/data

calls this API on an audience destination endpoint to add audience data to a specified new or existing audience.

About this API

calls this API when users select the option to add audience data to an existing destination audience when they share audiences between endpoints. also calls this API when users select the option to create a new audience. provides the audience data as a list of comma-separated values (.csv).

provides additional information about the audience data, such as the endpoint and segment ID for the source of an audience, in several URL parameters in the API call. These parameters are optional. The destination endpoint must determine how it uses the additional information.

Request

specifies specify the segment ID of the audience to which you want to add audience data.

The following example illustrates a request (using curl) to add audience data to a new or existing audience on a destination endpoint.

cURL

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}&currentBatchNumber={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.

Property

Use

Data type

Valid value

Description

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, divides the share into multiple batches.

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.

Text

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.

JSON

{
    "responseStatus": "success",
    "result": {
        "segmentId": "259",
        "numReceived": "4",
        "numInvalid": "0",
        "numAdded": "4"
    }
}

Property

Use

Data type

Valid value

Description

segmentId

Required

String

Segment ID

The unique segment ID that identifies the source of the audience data.

numReceived

Optional

Number

Number of records received.

numInvalid

Optional

Number

The number of audience records that were not valid records.

numAdded

Optional

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

adds a maximum of 10,000 rows of audience data at a time. If the total number of rows to be added exceeds 10K rows, divides the data into multiple batches within the call, each of which contains no more than 10K rows.
provides additional information about the audience data in several URL parameters in the API call. The destination endpoint must determine how it uses the additional information.

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

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}&currentBatchNumber={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.

Property

Use

Data type

Valid value

Description

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, divides the share into multiple batches.

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

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

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.

Text

{
    "responseStatus": "success",
    "result": {
        "segmentId": "259",
        "numReceived": "1",
        "numInvalid": "0",
        "numAdded": "1"
    }
}

Property

Use

Data type

Valid value

Description

segmentId

Required

String

Segment ID

The segment ID of the destination audience.

numReceived

Optional

Number

Number of records received.

numInvalid

Optional

Number

The number of audience records that were not valid records.

numAdded

Optional

Number

Number of records that are added to the destination audience.

DELETE /v1/segments/{segmentId}/data

calls this API on an audience destination endpoint to remove audience records from a designated destination audience.

About this API

calls this API on an audience destination endpoint when users select the option to remove audience records when they share audiences.

provides additional information about the audience data in several URL parameters in the API call. The destination endpoint must determine how it uses the additional information.

Request

The following example illustrates a request (using curl) to remove audience data from an existing audience on a destination endpoint.

cURL

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>}&currentBatchNumber={<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.

Property

Use

Data type

Valid value

Description

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, divides the share into multiple batches.

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

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

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.

Text

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.

JSON

{
    "responseStatus": "success",
    "result": {
        "segmentId": "259",
        "numReceived": "1",
        "numInvalid": "0",
        "numRemoved": "1"
    }
}

Property

Use

Data type

Valid value

Description

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 about a year ago