Skip to main content

​
Account Type

The Account object represents a user in the Verisoul system. Each account has a unique identifier, an optional email address, and customizable metadata.

​
Structure

FieldTypeRequiredDescription
idstringYesUnique identifier for the account
emailstringNoEmail address associated with the account
metadataobjectNoKey-value pairs of custom data associated with the account
groupstringNoGroups must be enabled for the project to use this field. See Multi Accounting Groups for more information.
listsarrayNoArray of list names to add the account to during authentication. See 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.

​
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: 
{
  "id": "acc_123456789",
  "email": "user@example.com",
  "metadata": {
    "first_name": "John",
    "signup_date": "2023-01-15"
  }
}
Update 1: Overwrite an existing field 
// Request
{
  "metadata": {
    "first_name": "Jonathan"
  }
}

// Resulting account state
{
  "id": "acc_123456789",
  "email": "user@example.com",
  "metadata": {
    "first_name": "Jonathan", // Updated
    "signup_date": "2023-01-15" // Preserved
  }
}
Update 2: Add a new field 
// Request
{
  "metadata": {
    "last_name": "Smith"
  }
}

// Resulting account state
{
  "id": "acc_123456789",
  "email": "user@example.com",
  "metadata": {
    "first_name": "Jonathan", // Preserved
    "signup_date": "2023-01-15", // Preserved
    "last_name": "Smith" // 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): 
{
  "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): 
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
  • Custom lists can be used for flexible account categorization