# Experiment on custom Unit ID types

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

A custom Unit ID randomizes experiment bucketing on an identifier you choose, such as `companyID`, `accountID`, or a device ID, instead of the default `userID` or Statsig-generated Stable ID. For example, a task management tool can bucket by `companyID` so everyone at the same company gets the same experience and you measure impact at the company level. Use a custom Unit ID for B2B, session-level, or group-level experiments and feature gates.

### When to use custom Unit IDs

- **Organization-wide experiments**: Group users by `companyID` for company-wide consistency.
- **Session-based experiments**: Use a session or device ID to control the experiment within a specific session.
- **Group-level rollouts**: Target teams, regions, or other specific cohorts using a relevant ID type.

Follow these three steps to set up an experiment with a custom Unit ID. The following examples use `companyID`, but you can replace it with any ID relevant to your use case.

> **Note:**
>
> These steps also apply to feature gates, allowing you to partially roll out features based on custom Unit IDs.

---

### Step 1: Add `companyID` as a custom Unit ID

1. **Log into the Statsig Console**: Go to [Statsig Console](https://console.statsig.com/) and navigate to **Project Settings**.
2. **Find Custom Unit IDs**: Under _Manage Account > Info_, look for the **Custom Unit IDs** section.

   ![Custom Unit ID Settings](https://docs.statsig.com/images/tutorials/custom-id-types/console-add-custom-id.png)
3. **Add a New Custom Unit ID**:

   - Click the **Edit** button.
   - Enter `companyID` as the new ID type and provide a description.
   - Save the changes.

   ![Add Custom ID](https://docs.statsig.com/images/tutorials/custom-id-types/custom-id-add.png)

After adding a custom Unit ID, you can use it across all Statsig configurations: experiments, gates, layers, dynamic configs, and autotunes. You only need to configure it once per project.

### Step 2: Select `companyID` as the ID type in your experiment

1. **Create a New Experiment**:

   - Navigate to **Experiments+** in the Statsig Console.
   - When setting up a new experiment, find the **ID Type** dropdown and select `companyID`.

   ![Select Custom ID Type](https://docs.statsig.com/images/tutorials/custom-id-types/custom-id-selection.png)
2. **Complete Experiment Setup**:

   - Finish configuring your experiment as you would for any [user-level experiment](https://docs.statsig.com/guides/abn-tests).
   - Define your hypothesis, metrics, and target audience.

   After completing the setup, click **Save**.

When you choose the right custom Unit ID, Statsig places all users with the same `companyID` in the same experiment group, which makes it easier to measure performance at the group level.

---

### Step 3: Provide `companyID` in the Statsig SDK

To use the custom Unit ID in your application, provide it when initializing the Statsig SDK. The `customIDs` field in the Statsig user object lets you pass the `companyID` (or any other custom ID) along with the usual user information.

#### Example (JavaScript)

```javascript
var user = {
    userID: "some_user_id",       // Standard user identifier
    customIDs: {
        companyID: "some_company_id"  // Custom ID for grouping
    },
    // Other attributes (optional)
    email: "user@example.com",
    appVersion: "1.0.0"
};

// Initialize the Statsig Client
const client = new StatsigClient(sdkKey, user);

await client.initializeAsync();
```

- **`customIDs` field**: This allows you to pass a dictionary of custom IDs, including `companyID`, to ensure the experiment targets users based on that ID.

After providing the necessary IDs in the SDK, you can start logging events and fetching experiment configurations based on the custom Unit ID.

---