--- updatedAt: 2026-08-18T04:46:29.000Z agentTools: projectIndex: https://docs.castle.io/llms.txt --- # Lists Learn how to effectively create, manage, and utilize Lists in Castle to streamline fraud-related workflows and enhance security. # What you will learn from this guide This guide will help you understand **the concept of*Lists***: * What are lists used for? * How do you create and manage a list? * How do you utilize a list in a policy? # Before you start * Ensure you have access to [your Castle account](https://dashboard.castle.io/) with *admin* privileges. * Ensure you have followed our [Integration Guide](https://docs.castle.io/docs/integration-guide) for proper setup. # What is a *List*? *Lists* are a fundamental concept in Castle, designed to streamline fraud-related workflows. They have several notable features: * A list is a collection of entries of the same type, such as User ID, Transaction ID, IP address, or even custom attributes like a product ID in a marketplace. When you create a list in Castle, you must specify the type of items it will contain. * Lists can be color-coded for easy organization. For example, you might use a red color for lists containing items you wish to block. * Lists can be integrated with [Policies](https://docs.castle.io/docs/creating-a-policy) to control actions based on list membership or to automatically add items based on certain conditions. * Each item added to a list includes an author and an optional comment, providing clarity on who added the item and why. * **Advanced**: A list item can include a "secondary field," representing another value from a different field. This is typically used to approve a device for a specific user. When a secondary field is set, the list matches only if an event matches the primary **and** secondary value of the *same* list item. An event matching just one of the two is not a match, and any policy filtering on the list will not trigger. * **Advanced** Items in a list can have an expiration time, after which they are automatically removed. For example, you could create a dynamic IP block list that bans each IP for 24 hours. # What can I use a *List* for? *Lists* serve two primary functions: * Blocking or allowing entries that match. For example, you can create an IP block list linked to a policy to deny access whenever a matching IP is detected. This list can also be configured to automatically add IPs based on specific criteria. * Collecting items for later review. For instance, create a "Transactions for Review" list and add transaction IDs that require further investigation from the Explore view. # Managing *Lists* and list items ### Admin role required! You must have an admin role in the Castle Dashboard to create lists. ## Creating a new *List* Navigate to the [List management page](https://dashboard.castle.io/v2/lists) and click "Create List" in the upper right corner. You will be prompted to provide details that define your list configuration: Create List form
Field Description
**Name** - \*Required\*\* A descriptive name for your list, such as "Blocked IPs," which provides a high-level overview.
**Color** - \*Required\*\* A color to represent the list within the Dashboard UI. Colors help organize your lists, such as using red for blocking lists and green for trusted items, allowing you to easily distinguish between fraudsters and trusted users.
**Description** - \*Optional\*\* A detailed explanation of the list’s purpose.
**Primary Field** - \*Required\*\* Choose a field that the list items will represent, such as User ID, IP Address, or Device Fingerprint.
- \*Secondary Field
(Advanced)\*\* 		- \*Optional\*\* Choose a secondary field. This is particularly useful when you need to trust or block a specific device, but only for a designated user. Matching is an AND across both fields of the same list item: an event matching only the primary field does not match the list.
- \*Auto-archivation time
(Advanced)\*\* 		- \*Optional\*\* The default duration, in minutes, after which items in the list are automatically archived, starting from the time of item creation. You can override this value when creating individual list items. If no time is set, entries will remain in the list until manually archived. For example, to trust a device for a day, set the time to 1440 minutes (24 hours), after which the trust is automatically revoked.
### Select Primary and Secondary fields carefully Once a list is created, the `primary` and `secondary` fields cannot be changed ### Auto-archive refresh Each time an item is added, the auto-archive time resets to count from the creation of the most recent entry. ## Adding items to lists Once you've created a list, you can manually add items to it in three ways. ### 1. Manually, via the list management page Navigate to the list by clicking its name and select *Add to List* on the right: Manually adding items to a list ### 2. From the Explore view Open a group-tab corresponding to the *List* entity, select items, and then click *Add to List*: Adding items to a list from Explore view ### 3. From the User Details view Add users or devices to corresponding lists by clicking the *No Lists* button in the top right corner or by selecting the relevant device from the list on the right: Adding items to a list from User Details v You can also include items in additional lists by clicking on the name of the list in the top right corner: Adding to additional list from the User Details # Using *Lists* with *Policies* ## Connecting a *List* to a *Policy* *Lists* serve organizational purposes by default. To take action based on a list's contents, set up a *Policy* to evaluate the list and provide the appropriate response. 1. [Create a new list](https://dashboard.castle.io/v2/lists) , e.g., "Blocked IPs," specifying IP Address as the primary entity. 2. Visit the [Policies](https://dashboard.castle.io/policies/list) page and create a new policy. 3. Choose the appropriate action, e.g., "Deny" for an IP block list. 4. In the policy settings, select *Add Filter*, then *Lists*, and choose the lists you want to connect: Create Policy with Lists trigger condition ### Lists with a secondary field A policy filter on a list with both a primary and secondary field only matches when the event matches **both** values on the **same** list item. Example: a list with primary `IP address` and secondary `Email` used in an Allow policy will only allow traffic from that exact IP/email pair. A request from a listed IP with a different email is not allowed by that policy. 5. Activate the policy to ensure that matching data triggers the desired action. ### Policy order Policies are evaluated sequentially, so arrange them correctly to achieve the desired outcome. For example, if you create an IP block list, this should be put at the top to make sure matching IPs are always blocked. ## Automatically creating / removing list items based on a *Policy* Policies can be configured to automatically create or remove list items when conditions are met. This functionality is particularly useful for automatically placing users on a review list based on specific criteria, or for blocking IPs that exhibit abusive behavior. To automatically create a list item based on a policy, first ensure that you have [created the list](https://dashboard.castle.io/v2/lists) to which the policy will add items. Then, navigate to the [policies](https://dashboard.castle.io/policies) page and establish a new policy that specifies the criteria you are targeting (for example, "bot score over 90"). At the bottom of the policy configuration screen, you will find an *Actions* section. Here, you can designate which lists to add to (or remove from) when the policy is triggered. Add items to a list when a policy matches ### Auto-archive refresh occurs each time a policy matches, resetting the archivation time. # Using Lists with API and Webhooks All actions can be managed via API, allowing for custom workflows directly from your apps. See the [API reference](https://reference.castle.io/#tag/lists) for details. By integrating the API with [webhooks](https://docs.castle.io/docs/webhooks), you can maintain up-to-date synchronization, regardless of where list changes occur. Subscribe to relevant *List* events when setting up your webhook.