Segment API

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

Marketers define audiences by segmenting their customer databases to identify and select groups of individuals that share one or more specified characteristics. Exchange 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 Exchange to find audiences, get information about the audiences, and share audiences through Exchange. Endpoints that produce audiences must implement the segment API differently from endpoints that consume audiences.

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

Segment API implementation for Push-type audience consumers

When Exchange users send audience data to an endpoint, Exchange 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 Exchange segment APIs, so that Exchange can call them in response to user requests.

GET /v1/segments

Exchange calls this API to get a list of audiences (segments) that are defined on an endpoint. Exchange uses the API response to display the available audience sources and destinations in the Exchange 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 Exchange 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 Exchange supports. The Exchange user interface displays only supported audience types.

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

-Contact Lists
-Databases
-Queries

For audience consumer endpoints, Exchange 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, Exchange sets the type to contact lists.

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

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

{
    "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 Exchange user interface provides an option to display additional descriptive information. To display additional audience information to Exchange users, Exchange 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. Exchange displays the additional information in the Exchange user interface. Implement this API on endpoints that are either an audience producer or audience consumer.

About this API

Through the Audiences tab, Exchange users can request details about each source or destination audience. Exchange calls this API to provide the additional information to Exchange 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, Exchange 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 -v 
-X GET 
-H "Authorization: Bearer <endpoint-level authentication key>" 
-H "Content-Type: application/json; charset=utf-8” 
https://<endpoint URL>/v1/segments/{segmentId}

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

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

What to do next

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

GET /v1/segments/{segmentId}/data

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

About this API

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

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

Request

The following example illustrates a request (using curl) to return data from an audience. Exchange specifies the audience by passing the unique segment ID that identifies the 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

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

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

POST /v1/jobs

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

About this API

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

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

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

Response

A successful response returns a success code and includes a JSON payload that includes values that Exchange 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.

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

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

What to do next

Exchange 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}

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

Before you begin

Exchange calls POST v1/jobs to generate a job ID.

About this API

Exchange calls this API periodically to poll the source endpoint for the current job status. When the job begins to upload audience data, Exchange 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 -v 
-X GET 
-H "Authorization: Bearer <endpoint-level authentication key>" 
-H "Content-Type: application/json; charset=utf-8”
https://<endpoint URL>/v1/jobs/{jobId}

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

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

What to do next

After the job completes successfully, Exchange calls the audience source endpoint to upload the audience data.

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

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

Before you begin

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

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}

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

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

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

About this API

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

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

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

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

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 Exchange creates a new audience, the only option is to add members to the new audience. Exchange calls POST v1/segments/{segmentId}/data to add data to the newly created destination audience.

POST /v1/segments/{segmentId}/data

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

About this API

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

Exchange 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, Exchange divides the data into multiple batches within the call, each of which contains no more than 10K rows.

Exchange 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

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

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"
    }
}

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

Exchange 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, Exchange divides the data into multiple batches within the call, each of which contains no more than 10K rows.
Exchange 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 -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.

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

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

DELETE /v1/segments/{segmentId}/data

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

About this API

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

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

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

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"
    }
}