Skip to main content


Optimizely Knowledge Base

Custom Attributes: Capture visitor data through the API in Optimizely X

here are two versions of Optimizely
What version do you have?
Optimizely Classic
This is what the Optimizely Classic user interface looks like.
Optimizely X
This is what the Optimizely X user interface looks like.
. If you're using Optimizely Classic, check this article out instead.
relevant products:
  • Optimizely X Web Experimentation
  • Optimizely X Web Personalization
  • Optimizely X Full Stack

  • Capture specific attributes of visitors, like plan type
  • Target experiments or Personalization campaigns to those attributes with audience conditions
  • Segment your Results page by that attribute to view how certain visitors behave differently

Visitors to your website aren't all the same. They differ by plan type, language, and other characteristics. Sometimes, it's helpful to be able to segment the results of your experiments and Personalization campaigns based on these characteristics.

For example, imagine that you run a subscription media site and you're experimenting with value messaging across the site. Your results show a "win," but you'd like to see how visitors on different plan types (basic, plus, and premium) responded. For a more granular view, you'd create a custom attribute for visitors' plan types, then use it to dive deeper into experiment results. Maybe you'd find that your change performs well for basic and plus plans, but premium users reacted negatively. This insight would influence your next round of experiments and decision-making. 

Use custom attributes to segment your experiment results for more insight. This allows you to drill down into experiment results and discover how certain segments of visitors are behaving differently. You can also use custom attribute values to build audiences.

In Optimizely X Web, you can have up to 100 custom attributes.

You'll use the Optimizely JavaScript API to set the custom value of an attribute for a visitor. Here is an example on how the code appears:

  "type": "user",
  "attributes": {
    "123": "custom attribute value",
    "customAttributeApiName": "this is also a custom attribute value"

Do custom attributes sound a lot like custom dimensions? They're the same concept with a new name in Optimizely X! If you've been using custom dimensions in Optimizely Classic, learn how attributes work for you.

Create a custom attribute

Here's how to create a custom attribute. Scroll down for step-by-step instructions:


  1. Navigate to the Audiences dashboard. Click Attributes > Create New Attribute

  2. Name the attribute and enter the API Name. The API Name must be unique.

  3. Click Save Attribute.

Now you can make an API call for custom attributes. Use the Optimizely JavaScript API to set the value of a custom attribute for each visitor.

Create an audience

After you create a custom attribute, you can target experiments or campaigns to visitors who have that attribute.

Here's how to use attributes to define an audience, with step-by-step instructions below:


  1. Navigate to the Audiences dashboard and click Create New Audience.

  2. Enter a name for your new audience.

  3. Click Custom Attributes and select the attribute you want to add. Drag and drop the attribute under Audience Conditions to define your audience conditions.

  4. Click Save Audience.

That's it! You've used a custom attribute to create an audience. Use the audience to show experiments or campaigns to visitors who have that attribute.

Segment by custom attributes

You can use custom attributes to filter your entire Results page or the results for an individual metric; this is called segmenting. Segmenting results helps you get more out of your data by generating valuable insights about your visitors.

Learn more about segmenting your Results page.

Custom attributes vs. custom dimensions

If you're familiar with Optimizely Classic and custom attributes seem a lot like custom dimensions, you're right -- it's the same concept! Here's what you need to know:

  • In Optimizely X, we've renamed custom dimensions; now they're called custom attributes.

  • Custom attributes give you a way of creating and managing dimensions in Optimizely X.

  • We've raised the limit from 10 dimensions (in Classic) to 100 total attributes (in Optimizely X).

  • Custom attributes are only available in Optimizely X. You can't use them in Optimizely Classic.

  • Anytime there's audience incompatibility, like when a condition isn't fully supported by Optimizely X or Optimizely Classic, we'll show you a warning.

When creating custom dimensions in Optimizely Classic and custom attributes in Optimizely X, remember not to reuse the API names across platforms.