> ## 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.

# Rules

> A comprehensive guide to Verisoul's automated rules engine for fraud prevention

# Rules in Verisoul

Rules enable real-time, automated decision-making by defining conditions that trigger list actions. They form the dynamic component of your fraud prevention strategy, allowing you to automatically respond to fraud patterns as they emerge.

## Understanding Rules

Rules consist of three main components that work together to automate fraud prevention decisions:

### 1. Triggers

Triggers define when a rule should be evaluated:

| Trigger Type                  | Description                                                          | Use Case                                                                        |
| ----------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **First Session for Account** | Evaluates only on the first session associated with an account       | Account creation, initial signup screening                                      |
| **All Sessions**              | Evaluates on every session for an account                            | Ongoing monitoring, behavioral changes                                          |
| **ID Check Completed**        | Evaluates when an enrolled ID Check verification session completes   | Act on document signals, ID risk flags, verification decisions                  |
| **Face Match Completed**      | Evaluates when an enrolled Face Match verification session completes | Act on face-match results, device/network signals from the verification session |

**Note:** The `ID Check Completed` and `Face Match Completed` triggers require the session to be linked to an account at the time of rule evaluation. To achieve this, you can pass an `account_id` [when creating the session](/verifications/id-check/integration/initialize-session#account-id). Sessions without an account are not evaluated by rules; they return the raw model decision and have no list effects. Each trigger fires exactly once per verification session, when it completes.

### 2. Conditions

Conditions define the filtering logic that determines when a rule should fire.

**Available Fields:**
You can use any field available in the [Authenticate API response](/api-reference/session/authenticate) to create complex conditional logic. All fields on the account and session table in the dashboard are available to use in rules.

Example fields include:

* **Account Data**: `decision`, `account_score`, `bot`, `multiple_accounts`
* **Session Data**: `session.location.country_code`, `session.network.service_provider`, `session.proxy`
* **Email Intelligence**: `email.disposable`, `email.domain_type`, `email.email_score`
* **Network Signals**: `risk_signal_scores.proxy`, `risk_signal_scores.vpn`, etc.
* **Verification Data**: `verification.decision`, `verification.risk_score`, `verification.risk_flags`, and document signals such as `document_signals.is_id_digital_spoof` or the document's country

**Logical Operators:**

* **AND**: Fields from both account and session can be used
* **OR**: Currently OR cannot be nested inside an AND condition
* **Numeric Operations**: Scores are normalized to 0-100%
* **String Operations**: All string operations are case-insensitive
* **List Operations**: `is in`, `is not in` Can also be used on string fields

### 3. Actions

Actions define what happens when a rule's conditions are met:

| Action Type          | Description                               | Effect                                                                                 |
| -------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- |
| **Add to List**      | Adds the account to a specified list      | Moves account according to [list hierarchy](/action/lists#list-hierarchy-and-movement) |
| **Remove from List** | Removes the account from a specified list | Removes account from specified list only                                               |

## Rule Management and Versioning

### Rule Versioning

* **Immutable History**: Every rule update creates a new version
* **Audit Trail**: Complete history of rule changes is maintained
* **No Deletion**: Rules can be archived but never permanently deleted
* **Ledger System**: Once a rule triggers for an account/session, it remains in the history forever

### Rule States

| State        | Description                   | Behavior                                               |
| ------------ | ----------------------------- | ------------------------------------------------------ |
| **Enabled**  | Rule is active and evaluating | Processes all matching triggers                        |
| **Disabled** | Rule is inactive              | No evaluation occurs, but history is preserved         |
| **Archived** | Rule is retired               | No longer visible in active rules, but history remains |

### Rule Execution

**Processing Characteristics:**

* **Parallel Execution**: Multiple rules can trigger simultaneously on the same API request
* **Real-time Processing**: Rules are evaluated synchronously with API requests
* **Order Independence**: Rules execute in parallel, not sequentially
* **Conflict Resolution**: When multiple rules affect the same account, all actions are processed together

## List Movement Logic

### Standard List Hierarchy

Rules respect the standard list hierarchy when adding accounts to lists:

```
Allow List (highest priority)
    ↑
Main Account List  
    ↑
Block List (lowest priority)
```

**Movement Rules:**

* **Block → Main Account**: ✅ Allowed
* **Block → Allow**: ✅ Allowed
* **Main Account → Allow**: ✅ Allowed
* **Allow → Block**: ❌ Not allowed via "add to list"
* **Allow → Main Account**: ❌ Not allowed via "add to list"

### Simultaneous Add/Remove Operations

When both add and remove actions occur in the same API request:

1. All remove actions are processed first
2. All add actions are processed second
3. Final list membership reflects the net result

**Example Scenario:**

* Account is on Allow List
* Rule A: Remove from Allow List
* Rule B: Add to Block List
* **Result**: Account ends up on Block List

## Rules, Lists, and Verifications

Verification products (ID Check, Face Match) use the same lists and the same rule builder as the core platform. There are no verification-specific lists or rules — one account, one set of lists. Because lists are shared, effects flow in both directions, by design:

### Verifications affect the account

A rule triggered by a verification acts on the **account**, not just the verification session. For example, a rule "IF `risk_signals` contains `id_age_below_16` → Add to Block List" places the account on the Block List. That membership affects the account everywhere, including core-platform decisions and all past and future verification responses.

### Account lists affect verification responses

An account's list membership — however it got there (manual add, core-platform rule, or verification rule) — overrides the `decision` returned by `verify-id` and `verify-face` and shown in the dashboard:

| List Membership | Verification `decision` |
| --------------- | ----------------------- |
| **Block List**  | `Fake`                  |
| **Allow List**  | `Real`                  |

`risk_score` and `risk_flags` are never modified — they always reflect the model's actual analysis. The `lists` field in the response shows the account's list membership, so you can tell when the decision was overridden.

## Common Use Cases

### Email-Based Rules

* Block disposable email providers
* Allow trusted corporate domains
* Allow test accounts in development environments

### Geographic Rules

* Block high-risk countries
* Allow specific regions
* Handle VPN/proxy detection

### ISP and Network Rules

* Block risky internet service providers
* Allow certain corporate vpn IP's

### Verification Rules

* Block accounts with IDs issued by specific countries
* Block accounts that present certain risk signals
* Block accounts whose ID shows an underage flag
* Clear a false verification result by allow-listing the account