> For the complete documentation index, see [llms.txt](https://docs.lassomoderation.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lassomoderation.com/automation-and-review/lists.md).

# Lists

Lists are reusable sets of items that your [custom moderation rules](/automation-and-review/custom-moderation-rules.md) match against, for example a list of banned words, an allowlist of your own domains, or a set of trusted email domains. Instead of putting the values inside each rule, you keep them in a list and let any number of rules reference it. When you add or remove items, every rule that uses the list picks up the change automatically, without editing the rules.

{% hint style="info" %}
A list has no effect on its own. It only does something once a rule condition references it, for example a **Text** condition set to *contains any word* pointed at your word list. Whether a list acts as a blocklist or an allowlist is decided by the rule that uses it (*contains* versus *not contains*).
{% endhint %}

<figure><img src="https://720369-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEHJJyWYjMNTzFPyCUpfR%2Fuploads%2FUKswqnrcgXAMclHsxsd0%2FScreenshot%202026-08-04%20at%2015.49.12.png?alt=media&#x26;token=2a6a016a-4520-4858-b47c-80bf418394b4" alt=""><figcaption></figcaption></figure>

### What you can use them for

* Maintain word and phrase lists for profanity, spam or scam detection, shared across all your text rules.
* Allowlist your own domains, so rules only act on links that point elsewhere.
* Match email domains you maintain yourself with the **Email domain** condition, for example to allow signups from your own company's domains. For disposable email providers there is a dedicated **Email address** condition that needs no list, see [custom moderation rules](/automation-and-review/custom-moderation-rules.md).
* Treat users from specific countries or IP addresses differently, for example for regional compliance.
* Catch structured patterns that word lists can't express, such as ID numbers or obfuscated handles, with regex lists.

### List types

Every list has a type, chosen when you create it, that determines what it can hold and which rule conditions can use it:

* **Text**: words or phrases, including ones with spaces or special characters ("free money", "sh\*t"). Used by the **Text** condition, the user **Name** condition and text [custom attribute](/moderator-toolkit/custom-attributes.md) conditions.
* **Domains**: websites, entered as URLs (e.g. `https://example.com`). Used to match links in the **Text** condition and by the **Email domain** condition.
* **Phone Numbers**: phone numbers including their country code. Used to match phone numbers found in text.
* **Countries**: countries as ISO 3166-1 alpha-2 codes (e.g. `US`, `GB`, `NL`). Used by the **Location (country)** condition.
* **IP Addresses**: used by the **IP address** condition (available on the Pro and Enterprise plans).
* **Regexes**: regular expression patterns, for cases word lists can't express. Used by the *contains regex* matching option wherever text matching is available.

How matching works (whole word versus partial matching, case-insensitivity, normalization of accents and look-alike characters) is described per condition on the [custom moderation rules](/automation-and-review/custom-moderation-rules.md) page.

### Creating a list

Open **Lists** in the sidebar. Type a name, pick a type under **Select type of list** and click **Create new list**. The type cannot be changed later; the name can (open the list, change the name and click **Save**).

The number of lists you can create depends on your plan: 5 on the Free and Starter plans, 15 on Pro, and unlimited on Enterprise.

### Adding and removing items

Click a list to open it:

* Type a value in the **Add new item** section and click **Add**.
* An item that is already on the list is skipped ("Item already in list"), so a list never contains duplicates.
* Each item records when it was added and by whom, shown in the **Created At** and **Added By** columns. Changes are also recorded in the audit logs.
* To remove items, select them and click the **Delete** button that appears.
* Use the search box to find items on large lists.

Depending on the list's type, values are validated when you add them:

* **Countries** must be ISO 3166-1 alpha-2 codes, anything else is rejected.
* **Phone numbers** must include a country code. They are stored in a normalized format, so `+1-415-910-7311` is saved as `+14159107311`.
* **Domains** must be valid URLs.
* **Regexes** are validated when added. Invalid patterns, patterns of 200 characters or more, and unsafe patterns (for example with nested quantifiers) are rejected.

A list can hold up to 50,000 items. Regex lists are limited to 100 patterns.

<figure><img src="https://720369-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEHJJyWYjMNTzFPyCUpfR%2Fuploads%2FJsPIfLLZhGvlj6sPElCm%2FScreenshot%202026-08-04%20at%2015.49.46.png?alt=media&#x26;token=dd9f3d01-bd9f-401b-ba99-81f1e41e564f" alt=""><figcaption></figcaption></figure>

### Uploading a file

To add many items at once, use the **Or upload file** section on the list. Upload a `.txt` file of less than 5 MB with one item per line (a single line of comma-separated values also works). A few things to keep in mind:

* Uploads always append to the list, they never replace it. Items already on the list are skipped.
* The same validation applies as for single items. If any entry in the file is invalid, the whole upload is rejected; fix the file and upload again.

### Adding items while you moderate

Select any text inside a piece of content, anywhere in the dashboard (the content pages, a user's content or a review queue), and a small dialog appears offering to add the selection to a list. Lasso detects what you selected (a country, IP address, phone number, URL or plain text) and only offers lists of the matching type. Pick a list and click the **Add to** button to confirm.

This is handy while reviewing: highlight a new spam phrase and add it to your word list without leaving the queue.

<figure><img src="https://720369-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEHJJyWYjMNTzFPyCUpfR%2Fuploads%2FVj0HA1Q9GcHYGyIAsuLt%2FScreenshot%202026-08-04%20at%2015.51.00.png?alt=media&#x26;token=535e4d8c-7570-4c97-81b6-8987531f9b16" alt=""><figcaption></figcaption></figure>

### Testing a regex list

Regex lists have a **Test word on list** section. Type a value under **Word to test** and click **Test** to see whether it matches, and which of the list's patterns matched it. Use this to check new patterns before a rule starts acting on them.

### Using lists in rules

When you pick a list-based matching option in a [custom moderation rule](/automation-and-review/custom-moderation-rules.md) condition, a selector appears with your lists of the matching type. A few things to know:

* A condition can select multiple lists, their items are combined.
* Changes to a list apply to every rule that uses it, within seconds.
* Renaming a list is safe. Rules reference the list itself, not its name.
* The **Used in rules** column on the Lists page shows which rules use each list, with links to open them.
* If no list of the right type exists yet, the condition shows **No lists available**. Create the list first.

### Downloading and deleting lists

Admins have two extra controls on each row of the Lists page:

* The download icon saves the list as a `.txt` file with one item per line.
* The trash icon deletes the list, after a confirmation. Deleting a list cannot be undone.

A list that is used by a rule cannot be deleted ("Cannot delete list, it's in use by a rule"). Remove the list from every rule condition that references it first.

### Managing lists through the API

Lists can be managed from your own systems through the API, authenticated with your API key. In the API, the list `type` values are `strings` (Text), `urls` (Domains), `locations` (Countries), `phone_numbers`, `ips` and `regexes`.

**Get all lists** (the `items` field is the item count):

```
GET /api/v1/lists
```

```json
{
  "success": true,
  "lists": [
    {
      "id": "cln4sal9000d6saf8m5g12ifp",
      "createdAt": "2026-07-01T12:00:00.000Z",
      "name": "Banned words",
      "type": "strings",
      "items": 42
    }
  ]
}
```

**Create a list**:

```
POST /api/v1/lists

{ "name": "Banned words", "type": "strings" }
```

Returns `{ "success": true, "listId": "..." }`. Lists created through the API count towards your plan's list limit.

**Get a list with its items**:

```
GET /api/v1/lists/{listId}
```

```json
{
  "success": true,
  "list": {
    "id": "cln4sal9000d6saf8m5g12ifp",
    "createdAt": "2026-07-01T12:00:00.000Z",
    "name": "Banned words",
    "type": "strings",
    "items": ["free money", "spam phrase"]
  }
}
```

**Add items** (appends, never replaces):

```
POST /api/v1/lists/{listId}

{ "items": ["first", "second"] }
```

Returns `{ "success": true, "addedItems": [...] }`. `addedItems` contains only the values that were actually added, values already on the list are skipped silently. The same validation as in the dashboard applies, and an invalid value rejects the whole request with a 400 error.

**Remove items**:

```
DELETE /api/v1/lists/{listId}

{ "items": ["first"] }
```

Returns `{ "success": true, "deletedItems": [...] }`. Items are matched by their exact value.

Renaming and deleting lists is not possible through the API, use the dashboard for that. All endpoints are subject to [rate limits](/developers/rate-limits.md).

### Lists in webhooks

List changes are sent to your platform as `UpdateList` actions through [webhooks](/developers/webhooks.md), carrying the list's id and name, plus `words_added` and `words_removed` arrays when items change (the fields are named "words" regardless of the list's type). See the [webhooks](/developers/webhooks.md) page for the full payload.