Set up list attributes

  • Updated

This topic describes how to:

  • Use custom lists of data to target experiences
  • Create list attributes and create audience conditions based on them
  • Run experiments for groups of visitors not easily captured by other audience conditions

List attributes are a type of external attribute that enables you to segment visitors that are part of an audience you have already defined somewhere outside of Optimizely Web Experimentation. They let you import custom lists of users, and then create audience conditions based on those lists.

List Attributes are available with the Web Scale package in Optimizely Web Experimentation.

Some more common use cases for list attributes include:

  • Targeting your premium subscribers by uploading a list of cookies for each subscriber that you’ve identified offline

  • Targeting VIP members in your loyalty program by uploading a list of cookies for loyal customers from your data warehouse or business intelligence platform

  • Querying your analytics tool to target users who have signed up for your newsletter but never purchased anything

  • Uploading a list of cookies or query parameters from your email service provider for users who qualify for an upcoming promotion

  • Targeting users who live in ZIP codes with particular demographic traits or political affiliations

Your Experimentation terms of service prohibit you from sending any personally identifiable information (such as names, social security numbers, email addresses, or any similar data) to the Experimentation services, through list attributes or otherwise.

How list attributes work 

Imagine your data warehouse team has provided you with a list of customer account IDs in a CSV file. These accounts have been identified as having “high upsell potential,” and your goal is to target visitors from these accounts in an experiment with various upsell options, so you can determine which options are most likely to drive conversions.

The first thing you'll have to do is match visitors to your site with their account IDs. This is often done with the use of a cookie; if you aren't sure how this process works for your site, ask your web development team for help.

Once you have this information, you're ready to configure a list attribute. During the configuration process, you'll need access to the following information:

  • The name of the list (for this example, we will name the list “high_upsell_potential”)

  • The name and type of the on-site identifier for this list (for this example, we will use a cookie named account_id)

After uploading the CSV containing your list of account IDs to Optimizely Web Experimentation, you will build a segmented audience and launch an experiment targeted with that audience.

When a visitor logs in and your website creates an account_id cookie, the Optimizely Web Experimentation snippet will read it and send the cookie's value to the list attributes targeting service. If the account ID matches any of your lists, the targeting service responds with that information. Then the Optimizely Web Experimentation snippet reads the response to determine if your visitor matches your Optimizely Web Experimentation audience.

Create a list attribute

To create a list attribute:


  1. Open the project where you want to use list attributes for targeting (list attributes are defined at the project level).

  2. Go to Audiences > Attributes.

  3. Click Create New Attribute > External Attribute.

  4. Select List and click Create List Attribute to start the configuration wizard.

  5. Provide a list attribute name. Note that characters used in list attribute names are restricted to alphanumeric, hyphens, and underscores only.

  6. Configure the list type to reflect the type of data your list will contain:

    • Cookies

    • Query parameters

    • Global JS variables

    • ZIP codes

    When using the JS variable option, please ensure that the variable is global. You will not be able to refer to embedded properties using dot notation e.g. "object.locator_name".

  7. Enter the name of the object selected in the previous step as it occurs in your website environment. Optimizely Web Experimentation will use this information to match visitors who are active on your website with the contents on your list attribute.

  8. Click Next.

If you need to edit these settings later, return to the attributes dashboard and click on the name of your list.

Upload data 

Once you’ve created a list attribute, you'll populate the list with data, via one of three upload methods.

  • Direct upload lets you upload small lists (5mb or less) via your browser
  • Amazon S3 is a good option for larger lists
  • REST API may be suitable for some code-level integrations

Uploading fresh data to an existing list will overwrite the previous data contained in the list.

When formatting a list file, there are several best practices you should consider:

  • Files should be formatted as a CSV or TSV file

  • Each row should contain a single ID

  • The file should contain one column of data (the first column populated with IDs)

  • The file should have 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:


Files uploaded to List Attributes are processed in the order they are received, using infrastructure shared by all customers. This means that while we typically begin processing uploaded files immediately, processing may be delayed if other customers are uploading a large number of files.

Direct upload

If you have a small amount of data to upload (less than 5mb), you can upload it directly in the Optimizely Web Experimentation web interface via direct upload:

  1. In the project where you created your list attribute, go to the Attributes dashboard under Audiences > Attributes. List attributes are grouped together at the bottom of the page.

  2. Click the More actions icon to the right of the modified date and select Data Upload.

  3. In the direct upload tab, click the link to choose a file to upload. This opens a file browser where you can select the file which contains your list data.

Amazon S3

If your list is larger than 5 MB or you would like to programmatically upload list data (useful when you want to write a script to automatically keep your list data fresh), S3 is the preferred method.

  1. In the project where you created your list attribute, go to the Attributes dashboard under Audiences > Attributes. List attributes are grouped together at the bottom of the page.

  2. Click the More actions icon to the right of the modified date and select Data Upload.

  3. In the Upload via S3 tab, you’ll see credentials to access your list’s S3 bucket.

  4. Using these credentials, you can upload files in a variety of ways. The simplest approach is to use an S3 client application, such as Cyberduck. You can also upload files programmatically using the AWS CLI, an available SDK, or library.


You can update list attributes with a PATCH request via the REST API. To make a valid request, you need the following information:

  • A personal access token

  • The list attribute ID (accessible in the Upload Data panel for a List Attribute)


Create an audience

To use a list attribute to target an experiment, you’ll need to create an Optimizely Web Experimentation audience and add your list attribute as an audience condition:

  1. Go to Audiences > Saved.

  2. Click Create Audience.

  3. In the conditions list on the right side of the audience builder, you’ll find all your list attributes grouped together under the External Attributes heading.

  4. Drag a list to the left to add it to your audience.

  5. Click Save.