​
Lists in Verisoul

Lists are a fundamental tool for organizing accounts and implementing specific fraud prevention workflows. They allow you to categorize users and apply different treatments based on their status. For detailed API documentation on implementing Lists, see the Lists API Reference.

​
Types of Lists

​
Standard Lists

Verisoul provides three built-in lists that form the foundation of fraud prevention:
List NamePurposeEffect
Allow ListTrusted accountsMarks accounts as Real (affects decision field only)
Block ListRisky accountsMarks accounts as Fake (affects decision field only)
Main Account ListPrimary user accountsSets multiple_accounts score to 0

​
Custom Lists

Create your own lists for specific use cases such as:
  • High-risk users requiring additional verification
  • Users under review
  • Special access groups
  • Industry-specific categories

​
List Properties and Behavior

Key Characteristics:
  • Standard lists are mutually exclusive (one account, one standard list)
  • Custom lists can have overlapping membership
  • Standard lists are permanent and cannot be deleted
  • Custom lists can be created and deleted as needed
  • Lists can only contain account entities
Important Notes:
  • Dashboard updates require an API call to reflect in your application
  • Webhook notifications for list changes coming soon
  • Lists can be managed via both Dashboard and API

​
List Hierarchy and Movement

When accounts are moved between lists through Rules, they follow a specific hierarchy:

​
Standard List Movement Rules

  • Block List → Can move to Main Account List or Allow List
  • Main Account List → Can move to Allow List only
  • Allow List → Cannot be moved to other standard lists via “add to list” actions

​
Custom Lists

  • Accounts can be added to or removed from custom lists independently
  • Custom list membership doesn’t affect standard list hierarchy
  • Multiple custom list memberships are allowed

​
Managing Lists

​
Dashboard Management

Use the Verisoul dashboard to:
  • Create and manage custom lists
  • Add or remove accounts manually
  • Perform bulk operations with CSV imports
  • View list membership and statistics
For step-by-step instructions, see Dashboard List Management.

​
API Management

Use the Lists API to:
  • Create and delete custom lists
  • Add or remove accounts programmatically
  • Retrieve list contents and metadata
  • Integrate list management into your application workflows

​
Authentication-based List Assignment

You can also add accounts to lists automatically during the authentication process by including a lists field in the account object: 
{
  "account": {
    "id": "user-123",
    "email": "user@example.com",
    "lists": ["custom-list", "allow"]
  },
  "session_id": "00000000-0000-0000-0000-000000000001"
}
This approach allows you to categorize accounts at the time of authentication, making it easier to implement dynamic list assignment based on your application logic. Important: If a list specified in the lists array does not exist, it will be automatically created. This ensures the API call will not fail due to missing lists. Use good naming conventions: lowercase with dashes or underscores, avoiding special characters or whitespace (e.g., high-risk-users, beta_testers).

​
Best Practices

​
List Organization

  • Use clear, descriptive names for custom lists
  • Document the purpose and criteria for each list
  • Regularly review and clean up unused lists
  • Consider list hierarchy when planning automation

​
Account Management

  • Monitor list movement patterns to identify trends
  • Use custom lists for temporary categorizations
  • Leverage standard lists for final fraud decisions
  • Implement proper error handling for API operations

​
Integration with Rules

Lists work seamlessly with Rules to create powerful automated fraud prevention workflows:
  • Rules can automatically add accounts to lists based on conditions
  • Rules can remove accounts from lists when criteria change
  • Multiple rules can operate on the same lists simultaneously
  • List changes are processed in real-time during API requests
Need help implementing lists? Contact our support team at support@verisoul.com