---
title: Custom attributes: Capture visitor data through the API
slug: web-experimentation/docs/custom-attributes-capture-visitor-data-through-the-api
docTags: 
createdAt: 2026-07-20T15:44:24.845Z
---

- Optimizely Web Experimentation
- Optimizely Personalization

Visitors to your website differ by plan type, language, and other characteristics. Sometimes, segmenting the results of your experiments and personalization campaigns based on these characteristics is helpful.

For example, if you run a subscription media site and you experiment with value-messaging across the site, your results may show a "win," but you want to see how visitors on different plan types (*basic, plus,* and *premium*) responded. To see a refined view, create a custom attribute for visitors' plan types, then use it to look deeper into experiment results. You may 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](docId\:mrUblIuNVOZc1dvjWdsbw) and examine how different segments of visitors are behaving. You can also use custom attribute values to build [audiences](docId\:t4-tpQf64GRofnzZhgi_T).

:::hint{type="danger"}
**Warning**

The Experimentation terms of service prohibit you from sending any personally identifiable information (PII) such as names, social security numbers, email addresses, or any similar data to the Experimentation system through list attributes or other features.
:::

Use the [Optimizely Web Experimentation JavaScript API](docId:1dLEYI3XpG0gwe0yaBzp4) to set the custom value of an attribute for a visitor. For example:

```javascript
// This line is required if the custom event is triggered before Optimizely is 
defined on the page or if triggered in Project JavaScript
window.optimizely = window.optimizely || [];
 
  window["optimizely"].push({
    "type": "user",
    "attributes": {
      "123": "custom attribute value",
      "customAttributeApiName": "this is also a custom attribute value"
    }
  }); 
```

## Create a custom attribute

1. Go to **Audiences** > **Attributes** > and click **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 Web Experimentation JavaScript API](docId:_kK0veAk1eNQdMVbT_Jjf) to set the value of a custom attribute for each visitor.
   For information, see the following:
   - [List attributes and table attributes](docId\:TkMGnjg_rQf6NCd2SuBpq).
   - [Configure list attributes](docId\:Ua8rT10ZkIkp8D03ofkxW).
   - [Improve custom attribute persistence using browser cookies](docId:_Ja0DHP-2l41fJKIO0n_Q).

## Create an audience

After creating a custom attribute, you can target experiments or campaigns to visitors with that attribute. See also [Audiences](docId\:IEjofkHOmT2__WUVZ4aSd).

To use attributes to define an audience, follow the instructions.

1. Go to **Audiences** **>** **Saved** **>** and click **Create New Audience**.
2. Enter a name for your 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**.
   The custom attribute creates 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 Experiment 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. See [Segment your results](docId\:V2630KVX5TRdJX6n2w3PL).