# Lists Source: https://docs.verisoul.ai/action/lists A comprehensive guide to managing user groups with Verisoul Lists # 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](/api-reference/lists/get). ## Types of Lists ### Standard Lists Verisoul provides three built-in lists that form the foundation of fraud prevention: | List Name | Purpose | Effect | | - | - | - | | **Allow List** | Trusted accounts | Marks accounts as Real (affects decision field only) | | **Block List** | Risky accounts | Marks accounts as Fake (affects decision field only) | | **Main Account List** | Primary user accounts | Sets 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 * Lists can be managed via both Dashboard and API ## List Hierarchy and Movement When accounts are moved between lists through [Rules](/action/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 * Add or remove up to 10,000 accounts at once * View list membership and statistics For step-by-step instructions, see [Managing Lists](/dashboard/manage-lists). ### 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: ```javascript theme={null} { "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](/action/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.ai](mailto:support@verisoul.ai) # ML Models & Configuration Source: https://docs.verisoul.ai/action/ml-models-configuration Configuring Verisoul's machine learning models for your business Verisoul's machine learning models are the core of our fraud prevention system. This guide explains how configuration changes directly affect the risk scores returned by our API endpoints. ## Understanding Model Configuration Every customer starts with the same default configuration optimized for general fraud detection. When you make API calls to Verisoul's endpoints, the scores returned are calculated using your specific configuration. The Verisoul team can help tune these configurations to adjust how strict or lenient different signals are scored. For example, configuration changes can: * Lower the proxy risk score when a user is on Apple Private Relay * Increase the risk score when a device is linked to multiple accounts * Adjust how aggressively the API flags VPN usage * Change scoring thresholds for bot detection ## Available Configuration Options The following parameters can be configured to adjust your API response scores: ### Network Signals * Proxy detection sensitivity * VPN detection thresholds * Datacenter IP scoring * Tor exit node handling * Impossible travel detection ### Device Signals * Device fingerprinting strictness * Cross-device linking thresholds * Bot detection sensitivity * Behavioral biometrics weighting ### Account Signals * Multi-account detection thresholds * Account linking sensitivity * Email risk scoring for disposable/undeliverable domains * Historical fraud patterns ## Configuration Process Configuration changes are managed by the Verisoul team to ensure optimal performance. To request configuration updates: 1. Contact your Verisoul account representative 2. Describe your specific needs and use cases 3. Our team will analyze your requirements 4. We'll implement and test the changes 5. Monitor the results and adjust as needed ## Best Practices When considering configuration changes: * Start with default settings and monitor results * Identify specific patterns of false positives/negatives * Request targeted adjustments rather than broad changes * Allow time to measure the impact of changes * Consider your industry's unique fraud patterns ## Next Steps * Explore [Lists](/action/lists) and [Rules](/action/rules) for additional fraud prevention * Learn about [Blocking Bad Actors](/verifications/overview) with verifications * Track scores, signals and anomalies over time in [Overview and Analytics](/dashboard/analytics) # Action Overview Source: https://docs.verisoul.ai/action/overview Learn how to take action on Verisoul decisions # Taking Action on Verisoul Decisions After integrating Verisoul and receiving decisions on accounts - either through the API or dashboard - you'll need to implement strategies to block bad users while minimizing friction for legitimate users and eliminating false positives. Verisoul provides flexible options for implementing these decisions in your system. ## Implementation Approaches There are three main frameworks for implementing Verisoul decisions: 1. **Real-time Automated Blocking via API** 2. **Manual Review and Offline Batch Blocking** 3. **Integration with Custom Fraud Models** ## Real-time Automated Blocking Verisoul aims to automate the data science work needed for accurate user decisions. While Verisoul provides the decisions, you'll need to implement the actual blocking mechanism in your system. This is typically done alongside an authentication provider (e.g., Auth0's blocking API). The decision field can be tuned in two primary ways: ### 1. ML Model Configuration The machine learning models can be fine-tuned for your specific ecosystem: * Adjust sensitivity for multi-accounting detection * Configure proxy/VPN detection thresholds * Customize device risk parameters * Tune bot detection sensitivity * Modify email risk scoring * Calibrate how sub-scores contribute to the overall account score Contact the Verisoul team to modify these configuration values. They can help evaluate different scenarios or analyze disposition data based on downstream metrics like chargebacks. ### 2. Lists and Rules **Lists** help you organize accounts and enable specific workflows for different user groups. Verisoul provides several standard lists by default: * **Allow List**: Marks accounts as Real * **Block List**: Marks accounts as Fake * **Main Account List**: Sets multiple\_accounts score to 0 (useful for allowing one primary account for users with multiple accounts) **Important Notes about Lists:** * Standard lists (allow, block, main\_account) are mutually exclusive * Custom lists can contain overlapping accounts * Lists can be managed via both dashboard and API **Rules** provide real-time logic for automatically adding users to lists through a no-code interface. Rules consist of three components: * **Triggers**: When to evaluate (first session vs all sessions) * **Conditions**: Complex filtering logic using account/session data * **Actions**: Add to or remove from lists Key aspects of rules: * Multiple rules can run concurrently * Rules are versioned and maintain complete audit history * Can operate on both account and session-level data * Self-service rule creation in the dashboard, with backtesting (see [Building Rules](/dashboard/rules)) ## Progressive Security with Step-up Verifications To minimize friction for legitimate users while maintaining strong security, Verisoul supports a progressive security framework using step-up verifications. This approach allows you to: 1. Start with lightweight, frictionless checks for all users 2. Progressively add stronger verification requirements only when needed 3. Reduce false positives and support workload 4. Maintain security without compromising user experience ### Managed Verification Services Verisoul provides several managed verification services that can be triggered based on risk signals: * **Face Match**: Verify user identity through facial recognition * **ID Check**: Validate government-issued identification documents * **Phone Risk Detection**: Assess phone number risk and ownership * **Email Risk Detection**: Evaluate email address authenticity and risk These verifications can be implemented in various ways: * **Proactive**: Required during initial signup for high-risk segments * **Reactive**: Triggered when suspicious activity is detected * **Progressive**: Added as users access more sensitive features * **Risk-Based**: Applied based on risk score thresholds For example, you might: 1. Allow initial access with basic email verification 2. Request phone verification if risk signals increase 3. Require ID verification for high-value transactions 4. Add face match for suspicious account patterns This layered approach helps balance security and user experience while providing clear paths for users to verify their legitimacy when needed. ## Manual Review and Batch Processing For cases where real-time blocking isn't required or when you want additional human oversight, you can: * Review decisions in the Verisoul dashboard * Export data for offline analysis * Implement batch blocking processes ## Custom Fraud Model Integration For organizations with existing fraud detection systems, Verisoul's decisions and signals can serve as additional inputs to enhance your models. This allows you to: * Combine Verisoul's insights with your internal data * Create custom scoring models * Implement graduated response systems ## Next Steps * Learn more about [ML Models Configuration](/action/ml-models-configuration) * Explore [Lists](/action/lists) for organizing accounts * Create automated workflows with [Rules](/action/rules) * Set up [Verifications](/verifications/overview) for additional security # Rules Source: https://docs.verisoul.ai/action/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. This page explains how rules work. To create, backtest and publish them in the dashboard, see [Building Rules](/dashboard/rules). ## 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 | | - | - | - | | **Account Creation** | 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`, `risk_signal_scores.ip_reputation` (-1 to 1), `session.network.asn`, `session.network.subnet`, 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 # Delete Account Source: https://docs.verisoul.ai/api-reference/account/delete account-openapi.json DELETE /account/{account_id} # Get Account Source: https://docs.verisoul.ai/api-reference/account/get account-openapi.json GET /account/{account_id} # Get Account Sessions Source: https://docs.verisoul.ai/api-reference/account/get-account-sessions account-openapi.json GET /account/{account_id}/sessions # Get Linked Accounts Source: https://docs.verisoul.ai/api-reference/account/get-accounts-linked account-openapi.json GET /account/{account_id}/accounts-linked # Update Account Source: https://docs.verisoul.ai/api-reference/account/update account-openapi.json PUT /account/{account_id} # Submit Email Source: https://docs.verisoul.ai/api-reference/email-intelligence/post email-openapi.json POST /email This endpoint accepts an email for processing and returns a `request_id` for correlation. The full analysis result is delivered asynchronously through the `email.intelligence.completed` webhook. See the [Webhook Payload Reference](/email-intelligence/webhook-reference) for response fields and examples. # Submit Email Batch Source: https://docs.verisoul.ai/api-reference/email-intelligence/post-batch email-batch-openapi.json POST /email This endpoint accepts a batch for processing and returns a `batch_id` for correlation. Each email's full analysis result is delivered asynchronously through the `email.intelligence.completed` webhook. See the [Webhook Payload Reference](/email-intelligence/webhook-reference) for response fields and examples. # Public Redirect Source: https://docs.verisoul.ai/api-reference/face-match/public-redirect facematch-openapi.json GET /public/liveness-redirect This endpoint is meant for easy testing without having to do a backend integration. Note that this is not the recommended integration method and is intended only for temporary testing purposes. Since the redirect link is completely public, users can share it with others, which may lead to increased cost. The Public Redirect endpoint should be used with caution and only for temporary testing. It is not suitable for long term use. # Get Face Match Session Source: https://docs.verisoul.ai/api-reference/face-match/session facematch-openapi.json GET /liveness/session # Verify Face Source: https://docs.verisoul.ai/api-reference/face-match/verify-face facematch-openapi.json POST /liveness/verify-face # Verify Identity Source: https://docs.verisoul.ai/api-reference/face-match/verify-identity facematch-openapi.json POST /liveness/verify-identity # Public Redirect Source: https://docs.verisoul.ai/api-reference/id-check/public-redirect idcheck-openapi.json GET /public/liveness-redirect This endpoint is meant for easy testing without having to do a backend integration. Note that this is not the recommended integration method and is intended only for temporary testing purposes. Since the redirect link is completely public, users can share it with others, which may lead to increased cost. The Public Redirect endpoint should be used with caution and only for temporary testing. It is not suitable for long term use. The 'id=true' query parameter is required to include ID verification in the session. # Get ID Check Session Source: https://docs.verisoul.ai/api-reference/id-check/session idcheck-openapi.json GET /liveness/session The 'id=true' query parameter is required to include ID verification in the session. # Verify ID Source: https://docs.verisoul.ai/api-reference/id-check/verify-id idcheck-openapi.json POST /liveness/verify-id # Overview Source: https://docs.verisoul.ai/api-reference/introduction ## Verisoul API Verisoul provides a comprehensive set of APIs to help you integrate identity verification and fraud prevention into your applications. Below you'll find our core API sections. Manage user accounts, retrieve account information, and delete accounts Create, authenticate, and manage user sessions Create and manage lists of accounts Verify and validate phone numbers Verify liveness and deduplicate accounts Verify identity documents and match faces to ID photos ## Environments Verisoul provides two environments for API access: **Base URL:** `https://api.prod.verisoul.ai` Use this environment for your live applications with real users. **Base URL:** `https://api.sandbox.verisoul.ai` Use this environment for development, testing, and integration. Each environment requires its own API key. Make sure to use the appropriate API key for each environment. ## Authentication All API endpoints are authenticated using secure API keys. You can find your API key in the [Verisoul Dashboard](https://dashboard.verisoul.ai) under **Settings → API Keys**. See [API Keys and Webhooks](/dashboard/api-keys-and-webhooks) for creating and rotating keys. ### Using Your API Key Keep your API key secure and never expose it in client-side code. Your API key carries many privileges, so be sure to keep it secret. To authenticate your API requests, include your API key in the request headers using the `x-api-key` header: ```bash theme={null} curl -X GET "https://api.prod.verisoul.ai/list" \ -H "x-api-key: your-api-key-here" ``` # Add Account to List Source: https://docs.verisoul.ai/api-reference/lists/add-account list-openapi.json POST /list/{list_name}/account/{account_id} # Create List Source: https://docs.verisoul.ai/api-reference/lists/create list-openapi.json POST /list/{list_name} # Delete List Source: https://docs.verisoul.ai/api-reference/lists/delete list-openapi.json DELETE /list/{list_name} # Get List Source: https://docs.verisoul.ai/api-reference/lists/get list-openapi.json GET /list # Get All Accounts in List Source: https://docs.verisoul.ai/api-reference/lists/get-all-accounts-in-list list-openapi.json GET /list/{list_name} # Remove Account from List Source: https://docs.verisoul.ai/api-reference/lists/remove-account list-openapi.json DELETE /list/{list_name}/account/{account_id} # Phone Verification Source: https://docs.verisoul.ai/api-reference/phone/post phone-openapi.json POST /phone # Rate Limits Source: https://docs.verisoul.ai/api-reference/rate-limits Verisoul implements rate limiting to ensure service stability and availability for all customers. ## Default Limits By default, each project has the following rate limit: **900 requests per minute**. This limit applies across all API endpoints for that project. When you exceed this limit, API requests return a `429 Too Many Requests` HTTP status code. ## How Rate Limiting Works Rate limits are tracked per project across three windows. Every request must pass all three: | Window | What it measures | Purpose | | - | - | - | | **1 second** | Requests in the current second | Caps instantaneous spikes | | **6 seconds** | Requests in the last 6 seconds | Caps short bursts | | **60 seconds** | Requests in the last 60 seconds | Enforces your overall rate limit | Your allowed requests are counted over a sliding window (the last N seconds), not a fixed clock minute that resets at `:00`. ### Burstiness Each short window allows more traffic than a perfectly even rate would. That headroom is the **burst factor**: | Window | Burst factor | Meaning at the default 900 req/min limit | | - | - | - | | 1 second | **6×** | Up to \~90 requests in a single second (steady rate is 15/sec) | | 6 seconds | **3×** | Up to \~270 requests in any 6-second span (steady rate is 90 / 6 sec) | | 60 seconds | **1×** | Up to 900 requests in the last minute | So you can send traffic in bursts, but not dump your entire minute quota at once. ### Soft limit near the ceiling For the 6-second and 60-second windows, there is a soft zone above the limit (about **1.3×**). In that zone, requests are increasingly likely to be rejected. Past the hard ceiling, all requests are rejected. If a request is rate limited, the response includes: | Header | Description | | - | - | | `Retry-After` | Seconds to wait before retrying | | `X-RateLimit-Limit` | Your maximum requests for the window | Example response body: ```json theme={null} { "status": 429, "error": "Rate Limit Exceeded", "message": "Current rate limit is 900 requests per minute. Please try again later." } ``` Space retries using the `Retry-After` header rather than immediately retrying. Immediate retries are more likely to stay rate limited. ## Increasing Your Rate Limits If you require higher rate limits for your application, please contact us: * **Slack**: Preferred contact method for the fastest response * **Email**: [support@verisoul.ai](mailto:support@verisoul.ai) When requesting increased limits, please provide: * The `project_id` you are requesting a higher rate limit for * The new rate limit you're requesting * Justification for the increased limit (expected traffic volume, use case, etc.) Typically rate limit increases are only approved for enterprise customers. Our team will review your request and adjust your rate limits accordingly. # Authenticate Session Source: https://docs.verisoul.ai/api-reference/session/authenticate session-openapi.json POST /session/authenticate # Get Session Source: https://docs.verisoul.ai/api-reference/session/get session-openapi.json GET /session/{session_id} # Account Source: https://docs.verisoul.ai/api-reference/types/account Account object structure and behavior # Account Type The Account object represents a user in the Verisoul system. Each account has a unique identifier, optional identity attributes (email, phone, name, username), and customizable metadata. ## Structure | Field | Type | Required | Description | | - | - | - | - | | `id` | string | Yes | Unique identifier for the account | | `email` | string | No | Email address associated with the account | | `phone` | string | No | Phone number on file for the account, in E.164 format (e.g. `+14155550123`). Used for [multi-accounting phone matching](/signals-scores/multi-accounting). | | `first_name` | string | No | Account holder's first name. Combined with `last_name` for multi-accounting name matching. | | `last_name` | string | No | Account holder's last name. Combined with `first_name` for multi-accounting name matching. | | `username` | string | No | Username associated with the account. Used for multi-accounting username matching. | | `expected_countries` | array | No | Countries the account is expected to legitimately operate from, as ISO 3166-1 alpha-2 codes (e.g. `["US", "CA"]`). | | `metadata` | object | No | Key-value pairs of custom data associated with the account | | `group` | string | No | Groups must be enabled for the project to use this field. See [Multi Accounting Groups](/integration/advanced/multi-accounting-groups) for more information. | | `lists` | array | No | Array of list names to add the account to during authentication. See [Lists](/action/lists) for more information. | ## Email Address An Account can have have a string email address. Verisoul stores only one email address per Account. When updating an account with a new email address, the previous email address is replaced. ## Phone Number An Account can have one phone number, provided in E.164 format (e.g. `+14155550123`). Like email, Verisoul stores one phone number per Account — updating an account with a new phone number replaces the previous one, and omitting the field keeps the stored value. Before matching, the number is normalized: formatting characters (spaces, dashes, parentheses, dots) are stripped, and the result must be a valid E.164 number (`+` followed by 8–15 digits). Two accounts sharing a normalized phone number are linked with the full-strength `phone` match type. See [Multi-Accounting](/signals-scores/multi-accounting) for details. ## Username An Account can have one username. Updating an account with a new username replaces the previous one, and omitting the field keeps the stored value. Before matching, the username is lowercased and only letters, digits, `.`, `_`, and `-` are kept — so `Jane.Doe` and `jane.doe` match, while `jane.doe` and `janedoe` remain distinct. Two accounts sharing a normalized username are linked with the full-strength `username` match type. ## Name An Account can have a first and last name, passed as separate `first_name` and `last_name` fields. Each field is updated independently — a call that includes only `first_name` keeps the stored `last_name`. For matching, the available parts are combined into a single name and normalized: lowercased, with punctuation and diacritics removed (so `Jane O'Brien` and `JANE obrien` match). Providing either part enables name matching. Because names are far less distinctive than phone numbers or usernames, a name match is moderate strength: a name match alone never fully links two accounts, but name plus another match (device, network, email) does. ## Expected Countries The `expected_countries` field is a declaration of where the account should legitimately operate from. Sending a **non-empty** list replaces the entire stored array (so a country can be removed by sending a new list without it). Omitting the field or sending an empty list `[]` leaves the stored declaration unchanged. Once declared, sessions outside the expected countries carry the `outside_expected_countries` risk signal and raise the [location spoofing score](/signals-scores/location#location-spoofing-score) in proportion to how far outside they are. See [Expected Countries](/signals-scores/expected-countries) for how both work. ## Metadata The metadata object allows you to store custom data with each account. When updating metadata: 1. New fields are added to the existing metadata 2. Existing fields are overwritten with new values 3. Other existing fields are preserved ### Example: Metadata Updates Starting metadata state: ```json theme={null} { "id": "acc_123456789", "email": "user@example.com", "metadata": { "plan": "free", "signup_date": "2023-01-15" } } ``` **Update 1: Overwrite an existing field** ```json theme={null} // Request { "metadata": { "plan": "premium" } } // Resulting account state { "id": "acc_123456789", "email": "user@example.com", "metadata": { "plan": "premium", // Updated "signup_date": "2023-01-15" // Preserved } } ``` **Update 2: Add a new field** ```json theme={null} // Request { "metadata": { "referral_code": "FRIEND50" } } // Resulting account state { "id": "acc_123456789", "email": "user@example.com", "metadata": { "plan": "premium", // Preserved "signup_date": "2023-01-15", // Preserved "referral_code": "FRIEND50" // Added } } ``` ## Lists The `lists` field allows you to specify which lists an account should be added to. This field is available in both: * **Server-side API**: During authentication via `/session/authenticate` * **Client-side SDK**: Using the `Verisoul.account()` method This is useful for automatically categorizing accounts based on certain criteria. ### Example: Adding Account to Lists **Server-side (Authenticate API):** ```json theme={null} { "account": { "id": "niel-test-08-11-2025", "email": "niel30@beeble.com", "lists": ["custom-list", "allow"] }, "session_id": "00000000-0000-0000-0000-000000000001" } ``` **Client-side (Browser SDK):** ```javascript theme={null} await window.Verisoul.account({ id: "niel-test-08-11-2025", email: "niel30@beeble.com", lists: ["custom-list", "allow"] }); ``` **Important Notes:** * The account will be added to all specified lists during processing * If a list does not exist, it will be automatically created (this will not cause the API to fail) * Use good naming conventions: lowercase with dashes or underscores, no special characters or whitespace * Standard lists (allow, block, main\_account) follow the [list hierarchy rules](/action/lists#list-hierarchy-and-movement) * Custom lists can be used for flexible account categorization ``` ``` # Email Source: https://docs.verisoul.ai/api-reference/types/email Email object structure used in the Email Intelligence endpoints # Email Type The Email object is the request body for the [Submit Email](/api-reference/email-intelligence/post) and [Submit Email Batch](/api-reference/email-intelligence/post-batch) endpoints. It contains the email address to analyze, an optional flag to enable identity intelligence, and optional identity claims. ## Structure | Field | Type | Required | Description | | - | - | - | - | | `email` | string | Yes | The email address to analyze | | `identity_intelligence` | boolean | No | When `true`, enables deeper identity analysis including online presence detection, connected identity discovery, and claims verification. Defaults to `false`. | | `claims` | object | No | Identity claims to verify against data linked to the email. Only meaningful when `identity_intelligence` is `true`. | ## Claims Claims represent information your customer has provided that you want to verify against independent data sources. When `identity_intelligence` is enabled, Verisoul matches these claims against identity data linked to the email and reports whether each claim matches, partially matches, or does not match. | Field | Type | Description | | - | - | - | | `name` | object | The expected name of the email owner. You can provide `first`, `last`, or both. | | `name.first` | string | First name (e.g., `"John"`) | | `name.last` | string | Last name (e.g., `"Doe"`) | | `phone` | string | Phone number in a valid format. E.164 is recommended. | | `country` | string | Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). | ### Name You can provide a first name, a last name, or both. Verisoul compares the provided name(s) against names associated with the email across data sources. ```json theme={null} { "name": { "first": "John", "last": "Doe" } } ``` ```json theme={null} { "name": { "first": "John" } } ``` ```json theme={null} { "name": { "last": "Doe" } } ``` ### Phone Provide the phone number in a standard format. [E.164](https://en.wikipedia.org/wiki/E.164) (international with `+` prefix) is recommended, but national formats are also accepted. **Examples:** | Format | Example | | - | - | | E.164 (recommended) | `"+14155551234"` | | E.164 with country code | `"+442071234567"` | | National (US) | `"(415) 555-1234"` | | National (UK) | `"020 7123 4567"` | ### Country Provide the expected country as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. **Examples:** | Code | Country | | - | - | | `"US"` | United States | | `"GB"` | United Kingdom | | `"CA"` | Canada | | `"DE"` | Germany | | `"JP"` | Japan | | `"BR"` | Brazil | ## Usage ### In Submit Email Claims and `identity_intelligence` are provided at the top level alongside the email: ```json theme={null} { "email": "john.doe@example.com", "identity_intelligence": true, "claims": { "name": { "first": "John", "last": "Doe" }, "phone": "+14155551234", "country": "US" } } ``` ### In Submit Email Batch `identity_intelligence` is set at the top level and applies to all emails. Claims are provided **per email**, allowing you to verify different identities in a single batch: ```json theme={null} { "emails": [ { "email": "john.doe@example.com", "claims": { "name": { "first": "John", "last": "Doe" }, "country": "US" } }, { "email": "jane@company.com", "claims": { "name": { "first": "Jane" }, "phone": "+442071234567" } } ], "identity_intelligence": true } ``` # Changelog Source: https://docs.verisoul.ai/changelog New features and improvements across the Verisoul API, SDKs, and dashboard Everything we ship that changes what you can see or do. ## Exclude personal data from Verify ID Add `?excludePII=true` to `POST /liveness/verify-id` and the response leaves out `document_data`, `photo_urls`, and `video_urls`. Everything else is unchanged. Without the parameter you get the full response, as before. Webhooks are not affected. ## Move accounts between lists, and update a list description `PATCH /list/{list_name}` updates the description on a list. `POST /list/{list_name}/account/move` moves up to 1,000 accounts to another list in one call, and returns an outcome per account, such as `moved`, `conflict`, or `not_found`. ## Name signals on ID Check Document signals include `name_not_found`, which fires when the name is missing from the document, and `name_partially_missing`, which fires when only part of it is found. Both work as rule conditions. ## Authenticate rejects a body that is missing an account `POST /session/authenticate` returns `400` when the request body is missing a usable `account` object, for example when the keys arrive capitalized as `Account` and `Session_id`. These requests returned `500` before, so error handling keyed on the status code sees the new value. ## Account grids load in seconds Opening a list's accounts on a large project takes seconds. Measured on a project with 75 million accounts: the block list page at 3.5 seconds, down from 100 to 300 seconds, an unfiltered page at 2.6 seconds, a country filter at 2.8 seconds, and a 4.2 million member list at 3.3 seconds. ## Analyze with AI on ID Check and Face Match The AI investigation panel runs on verification sessions. The liveness video analysis and the captured photos feed into it. On accounts, the analysis reads your project's own scoring thresholds, the definitions of the lists the account is on, and the conditions of the rules it hit. ## Incomplete verification sessions ID Check and Face Match sessions that ended before they completed open from the grid. Photos and videos captured up to that point are in their tabs, and the sections that need a finished session carry a placeholder explaining what is missing. ## Dashboards for every customer Dashboards is in the sidebar for every customer, and you can build your own. Charts and tables built in an Agent chat can be added to them. ## Digital IDs on ID Check A digital ID comes back as a risk signal, and you can write rules on it. When a digital ID is on screen, the video analysis view shows the clips that apply to it. ## Rule building Domain Type, Country, and Mobile Languages offer value suggestions on **contains** conditions, with exact matches ranked first, so typing `us` gives United States. School ID and employee ID are available as document templates in rules. ## Numeric rule conditions require a value Conditions using `>`, `>=`, `<`, and `<=` match when the field they read has a value. A rule on `verification.id_age < 18` matches only when the document carries a readable date of birth. Missing values used to compare as zero, so rules of this shape match fewer accounts and sessions from now on. [Rules](/action/rules) The sessions table has a **Source** column, filterable by web, iOS, and Android, and a **Source Version** column you can turn on from the column panel. Both values show in the session side panel and come along in CSV exports. You can write rules on session source. Sessions from the iOS, Android, and Flutter SDKs now report the SIM carrier and the country that carrier operates in. Carrier country comes from the device, so it holds up when the IP is proxied. Every session returns `source` (`web`, `ios`, or `android`) and `source_version`, so you can tell which integration produced a session and which SDK version it ran. Linked accounts return `first_seen` and `last_seen`, showing when two accounts were first connected and when that link was last active. ## Account timestamp format `first_seen` and `last_seen` come back as normalized ISO 8601 timestamps, on the account itself and on linked accounts. Earlier responses passed through nanosecond precision, for example `2026-04-22T21:38:47.806000000Z`, so anything parsing these fields sees a different string from now on. [Account object](/api-reference/types/account) ## Sessions with an out of range country code A session persists even when network intelligence reports a country code outside the two letter form, such as `CN-TW` for Taiwan. The country code on that session is left unset, and the account behind it gets its scores, decision, and `last_seen` as usual. Sessions like these were dropped before, so they now appear in the sessions table and in Get Session. ## Rules and lists act on verification results Two rule triggers are live in the dashboard: **ID Check Completed** and **Face Match Completed**. Rules on these triggers can read the verification decision, risk score, risk signals, document country, ID age, and the rest of the verification response. Rules apply to the account behind the verification. A rule like `IF risk signals contains id_age_below_16 → Add to Block List` adds the account itself, tied to the session where the condition matched. List membership now flows through to verification decisions. Block-listed accounts return `Fake` on `/verify-id` and `/verify-face`, allow-listed accounts return `Real`. Both endpoints return `lists` and `rules` fields showing what was applied. If you already keep accounts on lists, some verification decisions will change to match the account decision. ## Automatic enrollment Pass an `account_id` when you create a verification session and we enroll the account once the session completes. Enrollment was previously a separate call that had to happen in the right order, and sessions that skipped it returned confusing `Fake` results. [Rules](/action/rules) · [Face Match session setup](/verifications/face-match/integration/initialize-session) · [ID Check session setup](/verifications/id-check/integration/initialize-session) ## Rule suggestions from the agent Ask the dashboard agent for a rule and it proposes conditions backed by backtest numbers from your own data, then hands off to the rule create form with those conditions filled in. Suggestions arrive disabled and the backtesting drawer runs on arrival, so you see what the rule would have caught before you turn it on. ## Online presence signals on email Email intelligence reports online presence in tiers. `no_online_presence` and `sparse_online_presence` come back as risk signals, `moderate_online_presence` and `strong_online_presence` as trust signals. All four work as filters on the email table. Rows scored before this change stay filterable on `online_presence_detected`. [Email Intelligence](/email-intelligence/overview) ## Risk signal details Sessions return `risk_signal_details`, a set of named reason codes that explain why a risk score is elevated. It comes back on Authenticate, Unauthenticated, and Get Session. * **Network**: 13 signals covering the proxy, VPN, and location scores, such as `ip_on_vpn_list` and `true_country_mismatch`. * **Device**: 22 signals covering device risk, such as `browser_tampering_detected` and `android_emulator_or_rooted`. This includes emulator and jailbreak detection, factory reset boot profiles, Play Integrity verdicts, and device brand signals. Signals stay consistent with the scores beside them. A clean proxy score carries no proxy signal, and an elevated score always carries at least one signal explaining it. A few factual signals fire independently of score level, so you can write rules directly against them. ## Mobile device facts Sessions from the iOS and Android SDKs return a `mobile` block: brand, model, RAM, boot count, uptime, battery, languages, and OEM integrity verdicts. Native sessions also improve the existing `device` fields with values a WebView masks or misreports. All of it works in rules, as filterable columns in the sessions table, and in the session side panel. You may need to enable the new columns to see them. [Risk Signals](/signals-scores/risk-signals) · [Mobile](/signals-scores/mobile) ## Android time settings signal Device risk signals include `android_manual_time_settings`, which fires when a device has automatic time or automatic time zone turned off. It works in rules and as a filter on the sessions table. ## Duplicate a rule, and create rules disabled You can duplicate an existing rule, which opens the create form with its conditions and actions filled in. The create and edit forms carry a **Status** switch, so you can save a rule disabled and turn it on once you have reviewed it. New rules default to enabled. ## Equals and not equals on lists Rules on the Lists field take **Equals** and **Not equals**. Matching is on exact list membership, so a condition on `advertiser 10` treats `advertiser 100` as a separate list. ## Account fields in the accounts table The accounts table shows a **Phone** column, with **Username**, **First Name**, **Last Name**, and **Expected Countries** available from the column panel. All five filter, and the filters sync to the URL. ## Share a view, and clear a custom date range Tables and analytics pages have a Share button beside the date picker. It copies the current URL, which already carries the date range and the filters you have applied. An active custom date range gets an X beside it that clears the range and returns the page to the default 7 day period. [Rules](/action/rules) Five optional fields are accepted on the account object, through Authenticate Session and Update Account: `phone`, `first_name`, `last_name`, `username`, and `expected_countries`. **Phone, name, and username feed multi-accounting.** They become additional identifiers for linking accounts. A shared phone number or username is a full match on its own. A shared name supports links alongside device, network, and email matches. Matches appear in linked accounts with their match type. Values are normalized behind the scenes, so `+1 (415) 555-0123` matches `+1-415-555-0123` and `José García` matches `jose garcia`. **Expected countries feed location spoofing.** Declare where an account should be operating, for example `["US", "CA"]`. Sessions from outside those countries, or far from them, factor into that account's location spoofing score. All five fields are optional and additive. Send nothing and behavior stays the same. Updating a field later works as you would expect, with last write winning per field. [Account object](/api-reference/types/account) · [Multi-Accounting](/signals-scores/multi-accounting) · [Expected Countries](/signals-scores/expected-countries) ## Upgraded real-time models We improved how device and network data is collected. Measured against the previous models: * 31% better catch rate on sophisticated proxies and anti-detect browsers * 10 to 14% fewer false positives on location spoofing and proxy/VPN, with the largest gains on slow networks * 18 to 20% faster session IDs and API responses ## AI agent in the dashboard There is an agent in the bottom-left corner of the dashboard. It has access to your project data in a privacy-preserving sandbox, which is never shared with model providers or used for training. It can run investigations, build charts, slides, and CSVs, and take actions such as adding accounts to lists. Prompts worth trying: * "Pull all accounts linked to at above 50% strength, three levels deep" * "Compare fake and suspicious users over the last 7 days against the prior 7. What is driving the change?" * "Here are 100 emails. Find their accounts and add them to the block list." * "Build a report on the last 30 days: fraud rates, key drivers, trends" The agent keeps per-user and per-project memory, so context you give it in one chat carries into later ones. You can react to its messages with feedback, which we review weekly. ## Face Match and ID Check We rebuilt the data processing and risk engine behind both products, and we now capture and return session video in the dashboard. * 30% more accurate ID data capture * 82% fewer false positive risk flags, while catching more fraud * Video makes phone handoffs, digital IDs, and background characteristics visible during review * ID Check returns a face age estimate on the verification response. * Network intelligence identifies satellite connections as a distinct connection type. * The `id_age` document signal description now states what it measures: the age derived from the date of birth on the document. * Email intelligence groups the Identity Intelligence signals together and marks them as such in the API reference. Face Match and ID Check responses include a URL for the recorded session video. The same video is available in the dashboard on the verification detail view. Video shows the context around a capture: a phone handed between people, an ID held up on another screen, and the surroundings the capture happened in. You can serve the Verisoul browser SDK from a subdomain you own, for example `verify.yourcompany.com`. Requests go to your domain and reach us behind it. Setup is a nameserver delegation on a subdomain you dedicate to us. We handle the certificate and keep it renewed. Traffic to a first-party domain gets past ad blockers and tracker blocklists, which raises the share of sessions that produce a full signal set. [Custom Hostname](/integration/custom-hostname) Sessions and accounts return a `location_spoofing` score. It combines the signals we collect about where a session claims to be and where it appears to actually be: timezone, locale, GPS where available, IP geolocation, and network routing. The score is in the API reference for Get Session and Get Account, in the sessions and accounts tables, and available in rules. [Get Session](/api-reference/session/get) · [Network Intelligence](/signals-scores/network) Email intelligence used to run only as part of a real-time session through `/session/authenticate`. It is now a standalone endpoint, so you can submit an email on its own and get a full assessment back. Email carries history, and history takes years to fake. It also links out to names, phones, and locations, which adds identity context to device and network signals. What comes back: * **Risk score** from -1 (high trust) to +1 (high risk), with a decision label of `high_trust`, `trusted`, `moderate`, `risky`, or `high_risk`, plus the trust and risk signals behind it. * **Online history and age**: how long the address has existed, where it has appeared, and breach history with dates. * **Social signals**: which platforms the address is registered on, such as Google, Facebook, and LinkedIn. * **Deliverability**: whether the address can receive mail, with a recommendation of `send`, `send_with_caution`, or `do_not_send`. * **Domain intelligence**: disposable, fresh, and fake domains, classified as personal, business, education, government, relay, or inactive. * **Identity intelligence**: pass an expected name, phone, and country, and we match those claims against external data, then return connected names and phone numbers. Batches of up to 1,000 emails go through the API or a CSV upload in the dashboard. Results arrive by webhook and appear in the dashboard within a few minutes. Email Intelligence replaces Manual Lookup. Data from Manual Lookup stays in the email table. [Email Intelligence](/email-intelligence/overview) # Accounts and Sessions Source: https://docs.verisoul.ai/dashboard/accounts-and-sessions Find accounts and sessions, and investigate the signals behind an account decision The **Investigate** section holds the project's records. **Accounts** lists each account with its decision, scores, lists and rule hits. **Sessions** lists each session with the network, device and location Verisoul observed. Every account opens into an investigation page that brings its signals, linked accounts, rule hits and sessions together. For what each score and signal means, see [Scoring Overview](/signals-scores/scoring-overview) and [Account vs Session](/signals-scores/account-vs-session). ## Tables | Table | Date range applies to | Notes | | - | - | - | | **Accounts** | **Last Seen** | Accounts active in the period | | **Sessions** | **Created At** | Covers the last 89 days | Quick search on **Accounts** matches account ID, email, multi-accounting group, phone and username. On **Sessions** it matches a full session ID, part of an account ID, or the account's email. A search covers every date the table holds, regardless of the date range. To find sessions by IP address, filter the **Network IP** column. **Ask AI** in the search box turns a sentence into filters and a sort. See [AI Agent](/dashboard/ai-agent). ## Downloads Downloads include every row that matches the current filters, date range and search, up to 5,000,000 rows, with all fields including hidden columns and account metadata. Downloading needs **Export data** (Analyst and above). ## Bulk actions Selecting rows on **Accounts** enables: | Action | Limit per operation | Guide | | - | - | - | | **Add to List** / **Remove from List** | 10,000 accounts | [Managing Lists](/dashboard/manage-lists) | | **Delete account(s)** | 100 accounts | [Deleting Account Data](/dashboard/delete-account) | Selecting all rows applies the action to every account matching the current view, up to the limit. ## Account investigation The account page shows the account's score, decision, identifiers, lists, metadata, first and last seen dates, and countries. From here you can **Analyze with AI**, add or remove the account from lists, or delete it. ### Account Signals **Risk Flags** groups the account's signals by multi-accounting, bot, device, network and volatility. A flag is high above 66% and moderate above 33%. Volatility flags use counts: | Flag | Moderate | High | | - | - | - | | Devices in the last 7 days | 3 or 4 | 5 or more | | Networks in the last 7 days | 7 to 12 | 13 or more | | Countries | 2 or 3 | 4 or more | **Email Signals** shows the email's risk score, domain details, and trust and risk signals. **Run Email Intelligence** submits the address for deeper analysis, which is billable. See [Email Intelligence](/dashboard/email-intelligence). **Multi-Accounting** shows linked accounts: * The graph draws the 50 strongest links. The table beside it lists up to 1,000. * A dashed line marks an account linked only by Apple Device Check. These are left out of **Total Linked**. * **Linked to blocked user** is true when a linked account is on a list whose name contains "block" or "banned". See [Multi-Accounting](/signals-scores/multi-accounting) for how links are made. **Hit Rules** lists the 100 most recent rule hits for the account. ### Session Signals The account's sessions from the last 89 days (up to 1,000), a map of their IP locations, and breakdowns of top ISPs, risky network connections, devices, languages, time zones and browsers. Risky network connections are sessions with a bot, proxy, VPN or datacenter score above 50%. ### Verifications For organizations with verifications, lists the account's ID Check and Face Match sessions. See [Reviewing Verifications](/dashboard/verifications). ## Session details A session opens in a side panel with its source (web, iOS or Android) and SDK version, risk flags and risk signals, rule hits, location, network, device, mobile details for app sessions, and behavior counts such as clicks, key presses and touches. ## Search **Search** in the sidebar, or the **/** key, finds accounts across the project by ID, email, phone or username. ## Permissions | Action | Viewer | Analyst | Editor | | - | - | - | - | | View accounts and sessions | ✓ | ✓ | ✓ | | Download CSV files | | ✓ | ✓ | | Change custom lists | | ✓ | ✓ | | Change **Allow**, **Block** and **Main Account** | | | ✓ | | Delete account data | | | ✓ | | **Run Email Intelligence** | | | ✓ | Admins have every permission. See [Managing Users](/dashboard/managing-users). ## Need Help? If you have any questions about accounts and sessions, please contact our support team at [support@verisoul.ai](mailto:support@verisoul.ai). # AI Agent Source: https://docs.verisoul.ai/dashboard/ai-agent Ask questions about a project in plain English and get answers, charts, files and list changes back The AI Agent answers questions about your Verisoul data. It writes and runs its own queries across accounts, sessions, verifications, rules and lists, and returns text, charts, tables or files. It can also draft rules and change list membership, and it asks for approval before any change that affects live decisions. It appears in three places: | Where | What it does | | - | - | | **AI Agent** in the sidebar | Full chats about a project, kept in your chat history | | **Analyze with AI** on an account, ID Check or Face Match session | An analysis of that record, with follow-up questions | | **Ask AI** in the Accounts and Sessions tables | Turns a sentence into filters and a sort | The agent works in a private sandbox for each project, and your data is never used to train models. ## Scope Each chat reads one project, chosen before the first message and fixed after it. The agent can use: * Accounts and sessions, with their scores, signals and list membership * Rules, their definitions, and every time each one fired * Verifications, including ID Check and Face Match photos * Live state from the Verisoul API, such as a list's current members * The Verisoul documentation, for product and integration questions Mention records with `@`, paste up to 1,000 IDs in one batch, or attach files (up to 20 per message, 25 MB each). Prompts worth trying: * *Pull all accounts linked to `{account_id}` at above 50% strength, three levels deep* * *Compare fake and suspicious users over the last 7 days against the prior 7. What is driving the change?* * *Here are 100 emails. Find their accounts and add them to the block list.* ## Outputs | Output | Notes | | - | - | | Charts and tables | Downloadable, and can be added to a [custom dashboard](/dashboard/dashboards), where they re-run on live data | | Files | CSV and Excel exports, slide decks, Word documents and PDFs | | Rule suggestions | Drafted from your data, with the number of accounts they would match today | The agent does not create or turn on rules. **Review in Rules** opens the [rule builder](/dashboard/rules) with the suggestion filled in and backtesting running, and you save it from there. ## Changing lists The agent can create lists and add or remove accounts, from pasted IDs, attached files, or its own findings. | Change | Behavior | | - | - | | Custom list, up to 1,000 accounts | Runs immediately | | **Allow**, **Block** or **Main Account** | Waits for approval | | Any list, more than 1,000 accounts | Waits for approval | An approval card lists the change. **Approve** runs it and **Reject** discards it. List changes through the agent need the **Change Allow and Block lists** permission (Editor and Admin). For other roles, chats are read-only. Analysts can still manage custom lists from the **Lists** page. ## Analyze with AI On an account, the analysis reads your project's scoring thresholds, the lists the account is on, and the rules it hit. On a verification session, it also reads the captured photos and the session video. **Open full chat** continues the conversation in **AI Agent**. Incomplete verification sessions cannot be analyzed. ## Memory The agent keeps notes between chats: * **Per person:** stated preferences, such as preferred chart types or recurring breakdowns * **Per project:** what it has learned about the project's data and fraud patterns, shared with everyone who uses the agent on that project Personal data and credentials are not stored in memory. ## Sharing Only the person who started a chat can share it. | Option | Who can see the chat | | - | - | | **Share with project** | Everyone with access to the project, read-only. They can continue in their own copy. | | **Share publicly** | Anyone with the link, without signing in, including files and messages added later | Turning off **Share publicly** disables the link immediately. Turning it on again creates a new link. ## Scheduled runs A prompt can run on a schedule through the [MCP server](/dashboard/mcp-access), using `agent_schedules_create` with a cron expression in UTC or as a manual schedule. Each run opens a new chat for the schedule's creator and uses that person's permissions. Creating schedules needs **Schedule agent runs** (Editor and Admin). ## Permissions | Action | Viewer | Analyst | Editor | | - | - | - | - | | Chat, **Analyze with AI**, **Ask AI**, share chats | ✓ | ✓ | ✓ | | Add charts and tables to dashboards | | ✓ | ✓ | | Change lists | | | ✓ | | Schedule runs | | | ✓ | Admins have every permission. See [Managing Users](/dashboard/managing-users) for custom roles. ## Need Help? If you have any questions about the AI Agent, please contact our support team at [support@verisoul.ai](mailto:support@verisoul.ai). # Overview and Analytics Source: https://docs.verisoul.ai/dashboard/analytics Track trust tiers, risk signals and anomalies over time, and open the records behind any number **Overview** is a project's home page: headline volumes, trust tiers, signal trends and geography for the selected period. **Analytics** breaks the same data into filterable tabs and highlights what changed against the previous period. Both are read-only. For charts you define yourself, see [Custom Dashboards](/dashboard/dashboards). For what the scores mean, see [Scoring Overview](/signals-scores/scoring-overview). Every change figure compares the selected period with the period of the same length just before it. ## Overview | Section | What it shows | | - | - | | Headline tiles | **All accounts** (accounts with a session in the period), **New accounts** (first seen in the period), **All sessions**, and **Verifications** and **Emails** when there is activity | | **Accounts by trust tier** | Daily **Real**, **Suspicious** and **Fake** counts, for all active accounts or new accounts only | | **Account Signals** / **Session Signals** | The share of accounts or sessions scoring above 30% on each signal, such as multi-accounting, bot, proxy, VPN and location spoofing | | **Geography** | Account volume by country, with each country's trust mix and share of **Fake** accounts | | Verification and email charts | Daily ID Check and Face Match results by trust tier, and email results by risk band | Session volumes are pre-computed and can lag the most recent few minutes of traffic. ## Analytics | Tab | Contents | Filters | | - | - | - | | **Accounts** | Trust tiers, risk signals with an adjustable threshold, risk flags, multi-accounting cluster sizes, sign-up anomalies | List, Group, Domain, Country | | **Sessions** | Session signals, session anomalies | Country, OS, Browser, Network type, ISP | | **Verifications** | ID Check and Face Match pass rates, completion rate, results, anomalies | Country, OS, Browser, Network type, Document type | | **Email** | Risk bands, disposable domain rate, email anomalies | Domain, Country | The **Verifications** tab appears for organizations that use verifications, and the **Group** filter for projects that use [Multi Accounting Groups](/integration/advanced/multi-accounting-groups). **Multi-accounting clusters** groups new accounts by how many accounts they link to (1, 2-3, 4-5, 6-10, 11-25, 26-50, 51+). See [Multi-Accounting](/signals-scores/multi-accounting) for how links are made. ## Anomalies Each tab ends with anomaly tables grouped by dimension, such as domains, countries, ISPs or risk flags. For each value, Verisoul compares its **share** of the tab's traffic in the selected period with its share in the previous period. Using shares keeps overall growth from flagging every value: a domain growing with your traffic stays quiet, while a small domain that triples its share stands out. | Pill | Meaning | | - | - | | **Volume** | Change in the value's share of all traffic | | **Risk Volume** | Change measured among Suspicious and Fake records only | | **New** | No records in the previous period | The pill color gives the verdict: red for a significant change in a risky direction, green for a significant improvement, blue for a traffic shift with a steady trust mix, and grey for no significant change. Detection needs volume: * Both periods need at least 500 records on the tab after filters. Below that, groups read **Waiting on more volume**. * A value needs at least 20 records across both periods to be flagged. Email anomalies map risk bands to trust tiers: **High trust** and **Trusted** count as Real, **Moderate** as Suspicious, **Risky** and **High risk** as Fake. ## Drilldowns Clicking a bar, line point or table row on Analytics offers to open the matching records in the Accounts, Sessions, ID Check, Face Match or Email table, filtered to that value and period. A click on a time series narrows the table to that day. Items with no matching table column open without a panel. ## Permissions Overview and Analytics need **View analytics**, which every project role holds. Opening the records behind a number uses the permissions of the table it opens. See [Managing Users](/dashboard/managing-users). ## Need Help? If you have any questions about Overview and Analytics, please contact our support team at [support@verisoul.ai](mailto:support@verisoul.ai). # API Keys and Webhooks Source: https://docs.verisoul.ai/dashboard/api-keys-and-webhooks Manage project API keys and signed webhooks API keys let your backend call the Verisoul API for one project. Webhooks send a project's events to your endpoint, signed so you can verify they came from Verisoul. Both are managed under **Settings**, in tables covering every project you can access. The keys on this page are project API keys. Keys for AI clients are separate; see [MCP Access](/dashboard/mcp-access). ## API keys A project API key has full access to the Verisoul API for its project, including the **Allow** and **Block** lists. Send it in the `x-api-key` header, as shown in the [API Reference](/api-reference/introduction). Client SDKs identify the project by its Project ID and never need a key. | Property | Detail | | - | - | | Scope | One project, in one environment | | Format | 40 characters of letters and digits | | Expiry | None. A key works until it is deleted. | | Keys per project | Several can be active at once | | Activation and revocation | Take effect within about a minute | ### Who can see a key Only people with **Manage API keys** on a key's project (Editors and Admins) can see or copy its full value. Everyone else sees the last four characters. A key grants full API access, so holding it would bypass role limits in the dashboard. ### Rotating a key 1. Create a new key in the same project. 2. Move your integration to the new key and confirm requests succeed. 3. Delete the old key. Deletion cannot be undone. Keep at least one key in every project you use. The dashboard also uses a project key for account and session pages, verification sessions, list changes, email submissions and webhook changes. Deleting a project's last key stops those features until a new key is created. ## Webhooks A webhook sends a `POST` request to your endpoint when a chosen event occurs in a project. **Email Intel Completed** (`email.intelligence.completed`) fires when an email analysis finishes; see the [Webhook Payload Reference](/email-intelligence/webhook-reference). Each webhook has its own signing secret, shown after creation and available in the table afterwards. Every delivery carries an `x-signature` header made with it. Verify it before trusting a payload, as described in [Webhook Signature Verification](/email-intelligence/webhook-signature-verification). * A new webhook is enabled when created. * While a webhook is disabled, events are not delivered, and they are not sent later. * Creating a webhook needs an API key in the project. The dashboard creates webhooks and turns them on and off. To change a URL or events, create a new webhook and disable the old one, or use the `webhooks_update` and `webhooks_delete` tools through the [MCP server](/dashboard/mcp-access). ## Permissions | Action | Viewer | Analyst | Editor | | - | - | - | - | | See which API keys and webhooks exist | ✓ | ✓ | ✓ | | See and copy API key values | | | ✓ | | Create and delete API keys | | | ✓ | | Create webhooks and turn them on or off | | | ✓ | Admins have every permission. Permissions apply per project. See [Managing Users](/dashboard/managing-users). Keys and webhooks belong to a project, so Sandbox and Production each need their own. A Sandbox key works against `https://api.sandbox.verisoul.ai`, and a Production key against `https://api.prod.verisoul.ai`. ## Need Help? If you have any questions about API keys and webhooks, please contact our support team at [support@verisoul.ai](mailto:support@verisoul.ai). # Custom Dashboards Source: https://docs.verisoul.ai/dashboard/dashboards Build charts and tables in plain English and keep them on dashboards that stay current A custom dashboard is a grid of charts and tables, called widgets, built by describing them in plain English. A builder version of the [AI Agent](/dashboard/ai-agent) writes the query and draws the result. The query is saved with the widget, so the dashboard re-runs it for whatever date range is selected. Dashboards belong to the project. Everyone who can view dashboards in the project sees all of them, and anyone with **Manage dashboards** can edit or delete any of them. ## Building a widget **Add widget** opens the builder, with a chat on one side and a live preview on the other. 1. Describe what to measure and how to break it down, such as *weekly verification pass rate* or *top 10 device risk signals, as a table*. Leave out the time period: widgets follow the dashboard's date range. 2. Type `@` to reference a specific table or column. **Explore data** lists everything the builder can query, with column descriptions. 3. Refine it in the same chat until the preview is right, then choose **Save to dashboard**. Charts and tables from an AI Agent chat can also be added with **Add to dashboard**, as long as they were built from a query that can re-run. ## What the builder can query | Data | Contents | | - | - | | Accounts | Risk scores and current decision per account | | Sessions | Device, network and location signals per session | | Verifications | Face Match and ID Check results and risk flags | | Rules | Rule definitions and every time a rule fired | | ID Check records | Document verification sessions and identity links across accounts | | Session signals | Detailed device and network signals, for the last 90 days | Widgets can be line, area, bar, horizontal bar, histogram, pie, grouped bar, stacked bar or scatter charts, or tables. Each widget is one query with one y-axis. The builder builds widgets only; investigations, list changes and file exports belong in the [AI Agent](/dashboard/ai-agent). ## Behavior * Widgets reload when the dashboard opens and when the date range changes. * Widget dates are whole days in UTC. * Tables return 200 rows by default, and up to 10,000 when you ask the builder for more. Charts read up to 10,000 rows. * **Edit in builder** saves the result as a new widget and leaves the original in place. * Layout, renames and resizes save for everyone who opens the dashboard. Deleting a dashboard or removing a widget applies to everyone in the project and cannot be undone. ## Permissions | Action | Viewer | Analyst | Editor | | - | - | - | - | | View dashboards | ✓ | ✓ | ✓ | | Chat in the builder | ✓ | ✓ | ✓ | | Create, edit and delete dashboards and widgets | | ✓ | ✓ | Admins have every permission. Dashboards can also be managed through the [MCP server](/dashboard/mcp-access) within the same permissions. Dashboards in Sandbox and Production are separate, since they belong to different projects. ## Need Help? If you have any questions about custom dashboards, please contact our support team at [support@verisoul.ai](mailto:support@verisoul.ai). # Deleting Account Data Source: https://docs.verisoul.ai/dashboard/delete-account Permanently delete an account and its personal data from a project Deleting an account removes its personal data from a project. It is typically used for GDPR and CCPA erasure requests. Deletion cannot be undone. ## Where to delete | Where | Accounts per operation | | - | - | | **Accounts** table, by selecting rows | Up to 100 | | An account page, with **Delete Account** | 1 | | An ID Check session linked to an account, with **Delete Account** | 1 | | The [Delete Account API](/api-reference/account/delete) | 1 per call | Each deletion is confirmed by typing `DELETE`. ## What deletion does We delete all PII about the account, including images, videos, email, phone and name. The account is also removed from every list, including **Allow**, **Block** and **Main Account**, and its links to other accounts are removed. Deletion applies to one project in one environment. An account that exists in several projects, or in both Sandbox and Production, must be deleted in each. The Accounts table and list pages reflect a deletion within a few minutes. ## If the account ID returns If your integration later sends a session with the same account ID, Verisoul creates a new account with no history. It does not inherit the deleted account's list memberships, so an account deleted while on **Block** returns unblocked. ## Permissions Deleting accounts needs **Delete account data**, held by Editors and Admins. An Admin can add it to a custom role, for example for the person who handles privacy requests. See [Managing Users](/dashboard/managing-users). ## Need Help? If you have any questions about deleting account data, please contact our support team at [support@verisoul.ai](mailto:support@verisoul.ai). # Email Intelligence Source: https://docs.verisoul.ai/dashboard/email-intelligence Submit emails for analysis from the dashboard and review the results **Verifications → Email** holds every Email Intelligence result in the project, whether it was submitted from the dashboard or through the [Email Intelligence API](/email-intelligence/overview). For what the scores, decisions and signals mean, see [Email Signals & Scores](/signals-scores/email) and [Deliverability Risk](/email-intelligence/deliverability-risk). | Tab | Contents | | - | - | | **Emails** | Every analyzed email, one row each | | **Batches** | Each batch, with its progress and error count | | **Analytics** | Daily volumes, with and without Identity Intelligence | ## Submitting emails **Submit Emails** accepts: | Method | Limit | | - | - | | **Single** | One email, with optional name, phone and country | | **Paste** | Up to 100,000 emails, one per line | | **Upload** | A CSV of up to 100,000 rows | Paste and upload create a named batch. Batch names can use letters, digits, spaces, underscores and dashes. Dashboard submissions go through the same API as your integration: they are billable, and a webhook subscribed to **Email Intel Completed** receives their results. ### CSV format | Column | Required | | - | - | | `email` | Yes | | `first_name`, `last_name` | No | | `phone` | No. E.164 is recommended, such as `+15550109988`. | | `country` | No. A two-letter code, such as `US`. | Columns with these names are mapped automatically, and others can be mapped by hand. Rows without a valid email are skipped. ### Large lists Lists over 1,000 emails upload in chunks of 1,000, all in the same batch. Keep the window open until the upload finishes; closing it stops the upload after the chunks already sent. Batches process at about 250 emails a minute per project, so 100,000 emails take about 7 hours. Single emails are processed ahead of batches. ## Identity Intelligence **Run Identity Intelligence** adds research on the person behind each email: connected names and phone numbers, registered online accounts, and a match of the submitted name, phone and country against that data. It costs extra, and applies to every email in the submission. See [Identity Intelligence](/email-intelligence/identity-intelligence). To add Identity Intelligence to an existing result, choose **Run Identity Intelligence** on the email's page, or **Run Email Intelligence** on an account page. Either creates a new request; the original result stays as it was. ## Results An email's page shows its decision, send recommendation, risk and trust signals, email and domain details, breach history, Identity Intelligence results when available, and the accounts in the project that use the address. New results take about 20 seconds to appear in the **Emails** table. The email's own page and its batch page show them as soon as they are ready. ## Permissions | Action | Viewer | Analyst | Editor | | - | - | - | - | | View emails and batches | ✓ | ✓ | ✓ | | Download emails | | ✓ | ✓ | | Submit emails | | | ✓ | Admins have every permission. **Submit emails for analysis** is marked billable in the role builder. The **Analytics** tab uses usage data, which needs **View usage** (Admin and Billing). See [Managing Users](/dashboard/managing-users). ## Need Help? If you have any questions about Email Intelligence, please contact our support team at [support@verisoul.ai](mailto:support@verisoul.ai). # Managing Lists Source: https://docs.verisoul.ai/dashboard/manage-lists Create lists and manage which accounts are on them from the dashboard A list is a named set of accounts in a project. Every project has three standard lists, and you can create custom lists alongside them. How lists affect decisions, and how accounts move between the standard lists, is covered in [Lists](/action/lists). | List | Name | Effect of membership | | - | - | - | | **Allow** | `allow` | Decision set to Real | | **Block** | `block` | Decision set to Fake | | **Main Account** | `main_account` | Multiple accounts score set to 0 | | Custom lists | Your choice | None on the decision. Used for review, rules and reporting. | ## Creating a list **Create New List** on the **Lists** page takes a name and a description. Names are normalized to lowercase, with spaces and hyphens turned into underscores and other characters removed, so *High Risk - Q3* becomes `high_risk_q3`. Rules, the API and your integration refer to the list by this name, and it cannot be changed later. Lists are also created automatically when a rule action or an authenticate call's `lists` field names a list that does not exist. ## Adding and removing accounts | From | How | Limit | | - | - | - | | A list's page | **Add Accounts to List**, then paste account IDs, one per line | 10,000 | | The **Accounts** table | Select accounts, then **Add to List** or **Remove from List** | 10,000 | | An account's page | **Add to List** or **Remove from List** | 1 | | A verification session's **Matches** tab | **Add to List** on a linked account | 1 | There is no file upload. To add from a CSV, paste its account ID column. Only accounts Verisoul has already scored can be added. Changes can take a few seconds to appear in tables and counts.