Below you will find more information about the JSON field category and line_item.category, how those are being extracted, what problems solve, and what customization is available.
Categories are supported on Receipts & Invoices API
API Docs https://api.veryfi.com/api/v8/partner/documents
About Veryfi Categories
Veryfi offers the option to categorize documents using the field "category". Veryfi creates an API account with a predefined list of categories, called Chart of Accounts (COA), which serve as the "general list of categories" unless the list is modified. Every new document submitted uses the most recent "general list of categories".
What are the various use cases served by Veryfi categorization?
Categories are used to classify and track different types of expenses to understand spending patterns and analyze financial data.
Veryfi data extraction caters to multiple use cases, each with its unique demands and priorities. Different use cases may prioritize different aspects of data extraction. For instance, while one use case might require the extraction of the manufacturer or lot numbers, another might place greater importance on determining the type of expense and the category to which it belongs.
Our experience has shown that categories are particularly relevant in the CPG loyalty vertical and expense management domains. Categories are crucial in these industries, facilitating efficient expense tracking, personalized marketing, and strategic decision-making.
Categories Management 101
New categories can be added to the general list through several methods:
Manual Addition: A new category can be added manually through the Veryfi Web Portal > Data Transformations>Categories>"Add New Category" option.
Automatic Addition: A new category is automatically added to the list of general categories every time the system assigns a new category (not seen before) from the list of "custom" categories, if sent.
Cumulative Effect: Each time a new category is added, this category becomes part of the "general list of categories". Every subsequent request uses the extended list of general 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 general 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.
Smart Categorization at Veryfi
Veryfi OCR API utilizes smart categorization at both the document and line item levels.
Smart categorization streamlines the data extraction process, ensures accurate categorization of expenses, and offers flexibility for users to customize categories according to their specific needs.
There are two types of categories at Veryfi:
category- a field in your JSON that represents the document-level categoryline_item.category- line items level category
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.
Currently, we are actively working on enhancing line item categorization to match the advanced categorization capabilities available at the document level. Our aim is to ensure that once the document is processed and the document level category is assigned, the line items are categorized based on the product or service information and previous categorizations made manually in the Web portal or via PUT API to update line item categories.
If your use case requires advanced smart categorization on a line item level or per client level using custom lists, please get in touch with [email protected].
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
Field Reference
Let's look at all the fields mentioned in this Article and their description:
Field | Description |
| A category predicted from sent categories, user categories, or default ones |
| A request parameter that users can use to provide the list of custom categories |
| A category predicted from Veryfi list if custom categories are used |
| A line type predicted from Veryfi list, e.g. food, product, service |
| Category taken from reviewed line item with same SKU and/or description. Otherwise from the document category |
| A vendor type predicted from Veryfi list, e.g. Taxi |