Importing and Exporting Audiences

A list of audience members can be imported and exported from the Data Portal via the API.

Importing an Audience

Audiences can be imported from a list of identifying values. On the website, this feature can be used via a file upload interface. When importing via API, the list of values must be compressed to a Base64-encoded string before it can be sent, as if it was a file upload.

Select the Identifier Type

A variety of information is available to be used as the identifying value. The various identifier types are documented here.

The list must contain only one identifier type.

Building the List of Audience Members

Each customer in the list should be separated by a line break. There should be no commas or other separating characters.

If this function was using the file upload, the file would contain a one-column table. However, since using the API skips the file upload process, the data should be formatted similarly in plain text.

A header row is optional. If using the API, it is generally easier to not have a header.

Convert Audience Member List to Base64

Once the list of audience members is formed, it must be converted to Base64 string programatically. This string will be included in the request body.

Form the Request Body

The request body contains several fields:

identifierType: Set to the identifier type included in your list
includesHeader: If a header row is included, the includesHeader parameter can be set to true to skip the first row. Otherwise, set it to false.
content: The Base-64 string of condensed data.
name: The name of the new audience.
description: (Optional) A description of the audience.
fileName: A filename for the data. This field is required, even if a file is not used in this scenario. Enter ‘filename.csv’ or similar placeholder data if a file is not used.

				
					{
  "identifierType": "taxIdNumber",
  "includesHeader": false,
  "content": "QmFzZS02NCBlbmNvZGVkIENTViBjb250ZW50IGhlcmUuLi4=",
  "name": "New Customers Ages 35-49",
  "description": "New customers added within the last 60 days who are in the 35-49 years age group.",
  "fileName": "2023_18to35_north_carolina.csv"
}

Send the Request

Perform a POST operation to importedCustomerAudiences with the request body created earlier.

POST /service/importedCustomerAudiences

If successful, the response contains customer counts and other information about the created audience.

If an error occurs, troubleshoot the list of members before it is encoded into Base-64 to ensure the data in valid and formatted correctly.

Exporting Audience Members

Audience members cannot be exported to a file via the API. However, a list of audience members can be gathered, which can then be formatted and stored as desired.

listCustomerAudiences

To gather the customers within an audience, you must first gather the ID of the audience.

Perform a GET operation on customerAudiences

GET /service/customerAudiences

				
					"items": [
    {
      "name": "Most valuable customers",
      "description": "New customers added within the last 60 days who are in the 35-49 years age group.",
      ...
      "id": "0399abedfd3d",...
      } ,....

From this list, find the audience ID that matches the audience with the name or description you desire.

listCustomerAudienceCustomers

Once the audience ID has been gathered, perform a GET operation on the list of customers for the requested audience. Replace {customerAudienceId} with the ID from earlier.

GET /service/customerAudiences/{customerAudienceId}/customers

A list of customers is returned, which may have more than one page of data. This function uses pagination, which means the function may need to be called multiple times to gather all of the data. For more on pagination, read our documentation on pagination and our guide for calling functions with pagination.

Once you have collected the full list of customers, the data can be exported and formatted however desired.