With List Attributes, you can target users that are part of an audience you have already defined somewhere outside of Optimizely. To do this, you'll import custom lists of users, and then create audience conditions based on those lists. Learn more about how to set up and use List Attributes.

To target an experiment with List Attributes, you must:

  1. Create a list, indicating where user IDs are stored in your web environment.
  2. Upload data to populate the list.
  3. Create an audience which uses your list in a condition.
  4. Attach the audience to an experiment.

List Attributes can be created via the Optimizely interface or programmatically using the REST API.

List Attributes are available with the Web Enterprise package in Optimizely X and are compatible with both Optimizely X Web and Optimizely Classic.

Remember, your terms of service prohibit you from sending any personally-identifiable information (such as names, social security numbers, email addresses, or any similar data) to Optimizely's services or systems through List Attributes or any other feature.

Please read the article on personally-identifiable information to learn more about sending data to Optimizely and managing your users' information.

Data Upload

Once you have created a list, you need to upload data before you can target users with a matching ID. Files uploaded via Direct Upload or Amazon S3 must have the following format:

  • CSV or TSV file
  • One ID per row
  • One column of data (the first column populated with IDs)
  • No header row (i.e. the first row should contain an ID)

A properly-formatted CSV file containing UUID-style IDs would look something like this if viewed in a spreadsheet:

Sample CSV screenshot

Note that uploading fresh data to an existing list will overwrite the previous data contained in the list.

You have many options for uploading list data.

Direct Upload

You can upload small list files (less than 5mb) directly via the Optimizely interface. This is a good option when you want to test out the feature or build a one-off list that won't need to be updated frequently in the future. For detailed instructions on how to use Direct Upload, read the Direct Upload section of the List Attributes KB article.

Amazon S3

Optimizely provisions an Amazon S3 folder for each List Attribute you set up in the web app. After you upload a file, we will parse it and populate your list with its data. Files uploaded via S3 have no size limit.

You can upload your files in several ways. The simplest approach is to use an S3 client application such as Cyberduck.

Using Cyberduck

After you have downloaded and installed Cyberduck, follow these steps to upload a file:

  1. Retrieve the list's AWS Access Key, AWS Secret Key, and S3 Import Path from the Optimizely interface (Audiences > Attributes > Your List > More Actions > Data Upload).
  2. Launch Cyberduck and create a new Bookmark (Bookmark menu > New Bookmark).
  3. Enter a descriptive name for the list and your AWS Access Key.
  4. Click "More Options" to enter the S3 Import Path.

    Datasource Descriptive Name window from Cyberduck

    Note: Cyberduck requires the full S3 import path, including both the optimizely-import bucket and the given s3_path. For example, if dcp/567/678 was the s3_path, you would need to use /optimizely-import/dcp/567/678.

  5. View your bookmarks and double-click to connect to the S3 bucket. Cyberduck will prompt you to enter the AWS Secret Key from Step 1.

    Cyberduck s3.amazon.com login window prompting Access Key ID and Secret Access Key

    You are now connected to your list's S3 bucket!

  6. Drag and drop the files to be uploaded using the Cyberduck interface.

Please note that this process may change in future versions of Cyberduck. See the official Cyberduck website for current documentation.


You can also upload files programmatically using the Amazon Web Services (AWS) Command Line Interface, an available AWS SDK, or an available library.

Retrieve the AWS credentials and S3 path from the list attribute endpoint.

After uploading a file to S3, check Upload History to confirm that your file has been processed. If you need to upload an updated version of your file, make sure that any files with the same name have already been processed. Unprocessed Files with the same name in the same S3 path may be processed out of order, which would prevent your updates from being detected.


You can upload list data by making a PATCH request to the list attributes endpoint. To do this, format your list as a comma-separated string and pass it as the value of the optional list_content key.