> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verisoul.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Account

> Account object structure and behavior

# Account Type

The Account object represents a user in the Verisoul system. Each account has a unique identifier, an optional email address, and customizable metadata.

## Structure

| Field      | Type   | Required | Description                                                                                                                                                  |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`       | string | Yes      | Unique identifier for the account                                                                                                                            |
| `email`    | string | No       | Email address associated with the account                                                                                                                    |
| `metadata` | object | No       | Key-value pairs of custom data associated with the account                                                                                                   |
| `group`    | string | No       | Groups must be enabled for the project to use this field. See [Multi Accounting Groups](/integration/advanced/multi-accounting-groups) for more information. |
| `lists`    | array  | No       | Array of list names to add the account to during authentication. See [Lists](/action/lists) for more information.                                            |

## Email Address

An Account can have have a string email address. Verisoul stores only one email address per Account. When updating an account with a new email address, the previous email address is replaced.

## Metadata

The metadata object allows you to store custom data with each account. When updating metadata:

1. New fields are added to the existing metadata
2. Existing fields are overwritten with new values
3. Other existing fields are preserved

### Example: Metadata Updates

Starting metadata state:

```json theme={null}
{
  "id": "acc_123456789",
  "email": "user@example.com",
  "metadata": {
    "first_name": "John",
    "signup_date": "2023-01-15"
  }
}
```

**Update 1: Overwrite an existing field**

```json theme={null}
// Request
{
  "metadata": {
    "first_name": "Jonathan"
  }
}

// Resulting account state
{
  "id": "acc_123456789",
  "email": "user@example.com",
  "metadata": {
    "first_name": "Jonathan", // Updated
    "signup_date": "2023-01-15" // Preserved
  }
}
```

**Update 2: Add a new field**

```json theme={null}
// Request
{
  "metadata": {
    "last_name": "Smith"
  }
}

// Resulting account state
{
  "id": "acc_123456789",
  "email": "user@example.com",
  "metadata": {
    "first_name": "Jonathan", // Preserved
    "signup_date": "2023-01-15", // Preserved
    "last_name": "Smith" // Added
  }
}
```

## Lists

The `lists` field allows you to specify which lists an account should be added to. This field is available in both:

* **Server-side API**: During authentication via `/session/authenticate`
* **Client-side SDK**: Using the `Verisoul.account()` method

This is useful for automatically categorizing accounts based on certain criteria.

### Example: Adding Account to Lists

**Server-side (Authenticate API):**

```json theme={null}
{
  "account": {
    "id": "niel-test-08-11-2025",
    "email": "niel30@beeble.com",
    "lists": ["custom-list", "allow"]
  },
  "session_id": "00000000-0000-0000-0000-000000000001"
}
```

**Client-side (Browser SDK):**

```javascript theme={null}
await window.Verisoul.account({
  id: "niel-test-08-11-2025",
  email: "niel30@beeble.com",
  lists: ["custom-list", "allow"]
});
```

**Important Notes:**

* The account will be added to all specified lists during processing
* If a list does not exist, it will be automatically created (this will not cause the API to fail)
* Use good naming conventions: lowercase with dashes or underscores, no special characters or whitespace
* Standard lists (allow, block, main\_account) follow the [list hierarchy rules](/action/lists#list-hierarchy-and-movement)
* Custom lists can be used for flexible account categorization

```
```