Categories are supported on both APIs
Fields:
category, default_caetgory, line.item.category
Fields
accounts.transaction.category
Categories Management
Categories can be accessed via Web portal: https://app.veryfi.com/categories/
How to add a category?
Manual Addition: A new category can be added manually through the Veryfi Web Portal > Data Transformations>Categories>"Add New Category" option.
Manually added categories are being added to the "default list"
Automatic Addition: A new category is automatically added to the list of "non-default" categories every time the system assigns a new category (not seen before) from the list of "custom" categories, if sent.
Automatically added categories are being added to the "non-default" list.
What is the default and non-default list of categories?
The default list is being used to categorize all requests when custom categories are not sent
Non-default list are categories that were added from a custom list of categories and maked in grayy.
What is a custom list of categories?
A custom list of categories can be sent using the "categories" request parameter:
categories: A comma-separated list of custom categories. Veryfi will attempt to match a document category, line items with the specified categories.
How to modify a category and what happens?
Categories can be modified through the Category section in the Veryfi web portal with the following options:
Rename a category: Change the category name while preserving document associations
Delete a category: Remove the category entirely from the system
Category Rename Workflow
When a user renames a category (e.g., "Travel" → "Rideshare"):
Document Updates: All documents previously assigned the old category name ("Travel") are automatically updated on Veryfi's side to reflect the new category name ("Rideshare")
Category List Updates: The general list of categories is updated with the new name
Future Processing: Subsequent API requests will use the updated category list, with "Rideshare" available as an assignment option instead of "Travel"
Category Deletion Workflow
When a user deletes a category:
Document Unmapping: Veryfi automatically unmaps all documents from the deleted category
Category Assignment: Documents that were assigned to the deleted category will have their category field set to null
List Updates: The deleted category is removed from the default list of categories
API Response Behavior
When a user makes a GET request for a document ID that previously had a modified category:
If the category was renamed: The updated category name will be returned (e.g., "Rideshare" instead of "Travel")
If the category was deleted: The response will show
category: null
The described behavior reflects Veryfi's standard system behavior for documents stored in your Veryfi account. For your implementation, these changes will not immediately affect previously synced documents in your systems, unless you re-fetch documents from the Veryfi database.
How does Veryfi Smart Categorization work?
Smart categorization is a part of the data enrichment process. At the document level, the system examines the categories associated with the user's account first. If no matches are found within the standard list, the model will apply the category it deems most suitable based on previous selections and patterns across all customers at Veryfi taking into account vendor domain and type. This ensures that the system can still provide relevant categorization even without explicit category assignments.
What if you have Custom Categories?
In addition, users have the flexibility to send a personalized list of their own categories.
When users provide their custom categories, the model attempts to match expenses with the specified categories, supporting multiple languages. However, it is important to note that the model relies on common sense assumptions when matching expenses. For instance, if an expense is from Burger King, it is expected that Veryfi will categorize it as "food" or related custom categories, but it is not expected to categorize it as "dinner with a colleague" or similar specific descriptions. The emphasis is on aligning the expense with broader, more general categories to ensure accurate and practical categorization within the Veryfi smart categorization system.
If you want to use your own categories, you can provide the list of categories along with a request; just use a request parameter categories. Please check out API Schema provided by Veryfi to determine the correct parameter type and format.
Please note that boost_mode turns off categorization along with some other enrichments if used in the same API request. If you want even more control, take a look at the field called default_category - is a category predicted by the Veryfi model from the Veryfi list of best known categories.
Three Primary Flows
Flow 1: Shared Categories List
Platform X operates as an expense management solution with multiple customers (end clients):
Using Veryfi's general categorization system for all customers
All Platform X clients' documents are categorized using the same shared "general list of categories" - managed by Platform X via Web Portal
Category selection uses document count/weight as decision factors
No end-user-specific categorization differentiation
Category Management:
General categories list maintained in Platform X's Veryfi account
All Platform X customers share the same expanding category pool
Client A: No categories sent → Uses general category list from Platform X account
Client B: No categories sent → Uses general category list from Platform X account
Flow 2: Shared Custom Categories List
Platform X operates as an expense management solution with multiple customers (end clients):
Using a shared custom category list controlled entirely on Platform X side
All Platform X clients' documents are categorized using the same shared custom category list sent with each API request
Category selection ignores the general categories list maintained in Veryfi account, but provides a predicted category in
default_categoryfield.No client-specific categorization differentiation, but full control over available categories
Category Management:
Custom categories list controlled and maintained by Platform X application logic
Platform X sends the same custom category list with every API request for all clients
This approach bypasses the general categories list that can be easily modified via web portal
All Platform X customers share the same controlled custom category pool
Workflow:
Client A: Shared custom list sent → Uses shared custom categories list controlled by Platform X
Client B: Shared custom list sent → Uses shared custom categories list controlled by Platform X
Benefits of This Approach:
Complete Control: Platform X has full control over the category list without relying on Veryfi's general categories list
Consistency: Ensures all clients use exactly the categories Platform X wants to provide
Isolation from General List: Ignores the general categories list that could be accidentally modified via web portal
Predictable Results: Category assignments are based only on Platform X's controlled list
Flow 3: Client-Specific Category Lists
Platform X offering personalized categorization that respects each end users client's unique business structure and category preferences.
Custom Category Lists: Send client-specific category lists with each API request
Client Isolation: Ensure categories from different clients never mix
Expected Workflow:
Client A: Custom categories list A sent → Uses only provided categories
Client B: Custom categories list B sent → Uses only provided categories
For Flow #3 please contact Veryfi for assistance to ensure proper implementation. If your use case requires complete separation between different client category lists (preventing any cross-contamination or shared learning between clients), please reach out to Veryfi
Turn Documents into Customer Insights
We understand the importance of the data classification Veryfi does, so we recommend you look at two other fields that Veryfi returns. If you are in the CPG loyalty or Expense management field, these might be important for you as they unlock customer insights and purchase behavior.
Meet line_item.type and vendor_type together with a line item and document level category and vendor_type Veryfi gives you a great tool to validate purchases and unlock cross-basket insights to fuel your loyalty marketing programs or empower expense management solutions by flagging items not covered by the company travel reimbursement policy faster.
E.g., a Hotel Folio with a line item type "alcohol" can be flagged instantly.
line_item.type-[room, tax, parking, service, fee, delivery, product, food, alcohol, tobacco, transportation, fuel, refund, discount, payment, giftcard, donation, toll, lottery]vendor_type-type predicted from Veryfi list: other|Grocery|Taxi|Fuel|Hardware|Online Shopping|Restaurant|Utilities|Hotel|Fast Food|Department Store|Convenience|General Contractor|Food|Car Repair|Coffee|Parking|Drugstore / Pharmacy|Airlines|Nurseries & Gardening|Auto Parts|Bakery|Transportation|Health|Building Supplies|Office Equipment
Success story with Veryfi helping Navan save up to 86% in out-of-policy spend
Check out Veryfi Product Intelligence to unlock even more product insights
Read more about line item fields insights in Veryfi Blog
Policy Spend is connected with Fraud always - read more about Veryfi Fraud Suite
Automation and Data Transformation
If you desire more control over the categorization process and define precise guidelines, you can create automation using rules. These rules can be designed to assign specific categories at both the document and line item levels based on predetermined criteria or conditions. Setting up these rules allows you to ensure that items are categorized according to your specific guidelines, allowing for a more tailored and consistent categorization process.
📚 Learn more about Business Rules Engine for ways to build Business Validation Frameworks