---
title: Lists
description: Lists are sets of values (user IDs, IPs, emails, fingerprints) that policies match against. Use them to encode allow, block, VIP, and known-fraud rules.
---

# Lists

A list is a set of values you can match against in a [policy](/docs/v3/concepts/policies) condition. Lists are how you encode rules that depend on _which user, IP, email, or fingerprint_, not _what kind of_ user, IP, email, or fingerprint. Allow lists, block lists, VIP lists, known-fraud lists: all the same primitive.

## What goes in a list

A list holds values of a single kind:

- User `external_id`s.
- IP addresses.
- Email addresses or domains.
- [Fingerprint](/docs/v3/concepts/fingerprints) IDs.
- Phone numbers.
- Country codes.
- Device IDs.

You manage list contents from the dashboard or the API. Policies reference lists by name.

## How policies use lists

The `in_list` [policy](/docs/v3/concepts/policies) condition matches when the value on the [evaluation](/docs/v3/concepts/evaluations) appears in the list:

> If `user_external_id in_list "vip-customers"` → `allow`.
>
> If `ip in_list "known-fraud-ips"` → `deny`.

Combine list checks with other conditions for finer rules, for example, "challenge unless the user is on the VIP list."

## Side-effect verdicts

Two [verdicts](/docs/v3/concepts/verdicts) mutate lists as a side-effect:

- **`add_to_list`**: the matching policy adds the user (or IP, email, fingerprint) to a configured list.
- **`remove_from_list`**: the inverse.

The list mutation is applied by Rupt before the evaluation returns, and the action itself is honored by your server. Use this pattern for "first offense" rules: record the user with `add_to_list` once, then a second policy with `in_list` denies on subsequent attempts.

## Practical patterns

- **VIP allowlist.** A high-priority policy that matches `user_external_id in_list "vip"` and returns `allow` short-circuits any later policy from challenging or denying these users.
- **Known-fraud blocklist.** A high-priority policy that matches `ip in_list "fraud-ips"` and returns `deny` cuts off repeat offenders before any other check runs.
- **Progressive enforcement.** First policy: `add_to_list "watching"` on suspicious signals. Second policy: `in_list "watching" AND` (any new offense) → `challenge`. Third policy: `in_list "watching" AND` (severe offense) → `deny`.