This article will help you:
  • Use custom lists of data to target experiences to visitors
  • Upload lists and create list targeting conditions based on them
  • Run experiments for groups of visitors not easily captured by other Audience conditions

Uploaded Audience Targeting is an advanced Audience condition that enables you to target and optimize experiences to audiences built from your own business data.

Uploaded Audience Targeting essentially lets you import custom lists of users, and then create Audience conditions based on that information.


This feature is available on select Optimizely Personalization plans. Click to learn more about Optimizely Personalization.

How might you use Uploaded Audience Targeting?

  • Target your premium subscribers by uploading a list of cookies for each subscriber that you’ve identified offline
  • Target VIP members in your loyalty program by uploading an list of cookies for loyal customers from your data warehouse or business intelligence platform
  • Target users who have signed up for your newsletter but never purchased by querying your analytics tool
  • Upload a list of cookies or query parameters from your email service provider for users who are going to qualify for an upcoming promotion
  • Target users who live in ZIP codes with particular demographic or political affiliation by uploading a list of ZIP codes you would like to target

Remember that 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 the Optimizely services, through Uploaded Audience Targeting or otherwise.

Looking for some troubleshooting tips that are available only for internal-agents? Check on this link for information on how to:

  • Check if the file is correctly formatted within AWS
  • How to check your current location's data & see what you qualify for
  • How to verify if the values in a CSV file are separated by commas
  • How to create CSV file that separates each value with commas using Microsoft Excel
  • How to create CSV file that separates each value with commas using Terminal

Create a list

There are two ways to create and add lists into Optimizely: the List Upload Manager or the REST API.

If you’re just starting out or have a one-off list you’d like to target, you can upload it using the List Upload Manager. To do this, you’ll upload a CSV or TSV file and match your list based on a list of either cookies, query parameters, or ZIP codes. See below for how to do that.

It can take up to 2 hours for a lists to upload and be available for targeting.


We do not currently support editing a list via the List Upload Manager once it’s uploaded. If you need to re-upload a list, please delete the current list and create a new list, or re-upload it via the API.

You can also create lists via our REST API. The REST API lets you schedule jobs to continuously update lists. Just make sure that the list you're importing through the API is comma-delimited (for example: 123,456,789,012).

Here’s how to upload a list using our List Upload Manager:

  1. Go to the Home page > OverviewUploaded Lists. You'll see the uploaded audiences you've already posted. Click New Uploaded List to create a new list.

  2. Create a new list. Enter a name and description.

  3. Choose a CSV or TSV file to upload your list. The file should contain the information that you wish to target, separated by commas (no spaces). This is the query parameter or cookie values, or the ZIP codes. Make sure that you are using commas as the delimiter, not tabs, pipes, or anything else.
  4. Choose your list type, and enter your key name. In a list of query parameters or cookies, this would be the “key” (which is the section before the equal sign).

Let’s say you identify users by a query parameter called “userid,” which on your site would appear as a query parameter such as ?userid=123 or ?userid=999 -- in this example, the key (“userid”) stays the same but the values change. If you wanted to target both of these users (123 and 999) you would select “userid” as your key, then upload a CSV containing the values 123,999 (separated by a comma, no space).

By default, Excel (especially Excel for Mac), Numbers, and Google Sheets won't necessarily use commas to separate values in a CSV, especially on a Mac. If you're using these programs to create your list, consult with your technical team to make sure that your list is comma-delimited (in other words, separated by commas, with no spaces between values).

Target audiences based on a list

Once you’ve created a list, create an Audience from that list to target it in an experiment:

  1. Create a new Audience in Optimizely.
  2. Drag the Uploaded List condition to the Audience Conditions area.

  3. Choose the name of the list, and select is in or is not in to specify whether to include or exclude users in the list
  4. Add the Audience to an experiment to target that experiment.


Asynchronous targeting

List targeting is a first-load asynchronous call to Optimizely that happens after our main snippet (cdn.optimizely) loads.

Our targeting service will not block your page from first-load; if our targeting service times out then that user will simply not see any list targeted experiments. List Targeting was not built for first page load synchronous requests.

Restrictions on the list name

List names can have alphanumeric, hyphens, and underscores only. This is to ensure consistency in how the names are understood by the system.

File size and number of lists

Every customer is allowed a total of 1GB of list data at a time. The maximum list size 5 MB with a given entry having a 100 character limit. If you would like to upload lists larger than 5 MB, we recommended uploading separate lists and using “OR” audience targeting conditions.

Upload time
You may upload lists as frequently as you like, however, it may take up to 2 hours to propagate your lists to our servers