Introduction
The BANKSapi AI platform provides classification and analysis of financial data.
Endpoint Types
There are two complementary endpoint types.
Transaction-Level Endpoints classify individual transactions within bank products by spending categories, business partners, insurance types, and more.
User-Level Endpoints aggregate all bank products and their transactions to deliver comprehensive insights like contract detection, life stage analysis, credit risk assessment, and financial behavior patterns.
Building Blocks
Endpoints build upon each other, transaction classifications form the foundation for contract detection, which enables life stage analysis, which powers credit risk assessment.
This layered approach ensures consistency while maximizing the value extracted from financial data.
Standardized Classification
All endpoints use a standardized tagging architecture with Tag Instances linking entities to Tag Tree Items from hierarchical Tag Trees.
For example, in Categories, a grocery store transaction gets a Tag Instance linking to the Tag Tree Item LIVING_GROCERIES from the Tag Tree CATEGORIES.
This ensures consistent classification vocabularies across the platform.
Explore the Tags endpoints to understand available taxonomies and classes before diving into specific classifications.
Getting Started
Ready to start? Try Categories to classify each transaction of a bank product or Contracts to detect the contracts of a user across all his bank products.
Contact
Servers
Affinities
Identifies user interests and lifestyle patterns by analyzing spending behavior, contract relationships, and life stages to determine specific affinities for targeted product recommendations and personalized services.
Multi-Dimensional Detection System
The affinity detection engine operates across three complementary data sources:
- Contract Analysis - Analyzes existing contracts and insurance types to infer interests (e.g., gym membership suggests fitness affinity)
- Transaction Patterns - Examines spending frequency and amounts in specific categories over time
- Life Stage Integration - Correlates current life stages with typical associated interests and needs
Transaction-Based Detection
The system monitors spending patterns over a 6-month analysis window using sophisticated threshold-based detection:
- Frequency Thresholds - Detects consistent spending in specific categories (e.g., monthly gym memberships for fitness affinity)
- Transaction Count Analysis - Requires minimum number of transactions per month to establish genuine interest patterns
- Parent Category Matching - Can detect affinities at both granular level (specific merchants) and broader category level
- Statistical Validation - Uses percentage of months meeting criteria to ensure sustained interest rather than isolated events
Practical Applications
- Targeted Marketing - Deliver personalized product recommendations based on detected lifestyle interests
- Customer Segmentation - Group users by similar interests for focused campaign strategies
- Product Development - Understand customer preferences to design relevant financial products
- Cross-selling Opportunities - Identify users likely to be interested in specific services or partnerships
Example Affinities Detected
The system can identify various lifestyle and interest-based affinities, including:
- Sportive - Detects fitness enthusiasts through gym memberships and sports-related spending
- Pet owner - Identifies pet owners via pet-related expenses and animal insurance contracts
- Traveler - Recognizes frequent travelers through travel-related transaction patterns
- Foodie - Spots food enthusiasts based on dining out and culinary spending habits
- Fashion Enthusiast - Identifies fashion-conscious users through clothing and accessories purchases
- Parent - Detected through life stage analysis rather than transaction patterns
- Car Owners - Car owners identified through fuel purchases and vehicle-related expenses like taxes and insurance
- Technophiles - Technology enthusiasts detected via electronics purchases
- Avid Investors - Identifies investment-minded users through banking and investment transactions
- Home & Garden - Home improvement enthusiasts via furnishing and garden expenses
Extensibility and Customization
The affinity detection system is designed with extensibility in mind, allowing for future enhancements and customization:
- Extendable Category Mappings - The system can be extended to define which spending categories trigger specific affinities.
- Adjustable Threshold Values - Thresholds for spending frequencies and amounts can be adjusted to fine-tune detection.
- Configurable Time Windows - The analysis periods for different types of interests can be modified.
- Adaptable Detection Rules - New affinities can be added and existing detection logic can be adapted based on business needs.
This adaptability allows the system to be tailored to different market segments and evolving customer behavior patterns.
Operations
Get affinities tags
Returns detected affinities for a provided user.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Responses
Success, tags newly created or read from database
Affordability
Provides comprehensive affordability analysis by evaluating income, expenses, and financial behavior patterns to assess a user's creditworthiness and financial stability.
Practical Applications
- Credit Risk Assessment - Evaluate loan applications by analyzing expense-to-income ratios and payment behavior
- Financial Product Recommendations - Match users with suitable financial products based on spending patterns
- Investment Advisory - Determine safe investment thresholds based on discretionary income analysis
- Budget Planning - Help users understand their financial capacity for major purchases or commitments
Key Financial Metrics
The analysis generates comprehensive metrics across multiple dimensions:
- Income Analysis - Separates regular (contract-based) from irregular income streams
- Expense Categorization - Breaks down expenses into necessities and luxuries with detailed subcategory analysis
- Financial Ratios - Calculates critical ratios like expenses-to-income, luxuries-to-income, and necessities-to-income
- Discretionary Income - Computes available money after necessities for financial decision-making
- Savings Capacity - Determines monthly surplus or deficit based on income minus total expenses
Advanced Risk Indicators
The system monitors various financial health indicators:
- Credit Behavior - Detects existing loans, mortgage payments, and credit card usage patterns
- Payment Issues - Identifies return debits, reminder charges, debt collection, and seizure payments
- Gambling Activity - Tracks recreational gambling expenses as a risk factor
- Financial Literacy Score - Evaluates financial management competency based on account balances and transaction history
Data Processing Window
Analysis typically covers a 6-month historical window to ensure statistical relevance while capturing recent financial patterns.
The system intelligently adjusts the analysis period based on available transaction history and ensures sufficient data completeness for accurate predictions.
Necessity vs. Luxury Classification
Expenses are automatically classified using the categories tag tree system:
- Necessities - Essential expenses like rent, utilities, groceries, fuel, and basic insurance
- Luxuries - Discretionary spending including entertainment, dining out, non-essential shopping, and premium services
This classification enables precise calculation of discretionary income and spending flexibility for financial planning purposes.
Related Endpoints
credit-attributes- Provides complementary credit risk assessment with focus on creditworthiness indicators, life stage analysis, and detailed credit contract evaluation for comprehensive lending decisions
Operations
Get affordability tags
Returns comprehensive affordability analysis for a provided user.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Responses
Success, tags newly created or read from database
Cashflow
Provides cashflow statistics and predictions based on a user's full transaction history.
This endpoint analyzes a user's transaction history to generate comprehensive cashflow insights, including income and expense patterns, spending trends, and financial predictions.
The analysis categorizes transactions and provides statistical summaries to help understand financial behavior.
Key Features
-
Dual-Axis Analysis
Provides cashflow data organized by both categorization and time components.
You can switch the focus between the two dimensions, either sorted by categories on the outer level with time on the inner level, or vice versa. -
Multiple Time Aggregations
Time components include weekly, monthly, quarterly, annual, and total aggregations, allowing tailored analysis. -
Flexible Categorization
Uses eithercategoriesorbusiness-partnersas the categorization basis for organizing cashflow data. -
Predictive Analytics
Generates predictions based on historical data from the previous 12 cycles (e.g., 12 months), incorporating recurring transaction patterns from thecontractsendpoint for enhanced accuracy.
For instance, if the user's salary is pending for the current month, the prediction will account for this expected income.
Predictions are calculated for the current and the next cycle.
Therefore, the current cycle has both statistical and predictive data, while all other cycle only contain either statistics (past cycles) or predictions (next cycle).
Note: Currently, predictions are available when the focus of the analysis is on categorization according tocategories. -
Savings Filtering
Optional exclusion of savings transactions to prevent distortion of expense statistics when savings shouldn't be considered as regular expenses for specific use cases. -
Category Level Control
When usingcategoriesfor categorization, it's possible to limit to main categories only for higher-level analysis. -
Aggregated Totals
When the analysis focuses on time periods and usescategoriesas the categorization basis, special aggregated tag tree items are included:- NET (overall cashflow)
- INCOME (all income transactions)
- EXPENSES (all expense transactions)
These totals exclude transfer transactions to provide accurate cashflow summaries for each time period.
Note: These totals are not included when usingbusiness-partnerscategorization or when the focus is on individual categories.
Operations
Get cashflow tags
Returns cashflow analysis with statistics and predictions for a provided user.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Query Parameters
Cashflow is generated with the focus on either time or tag (CATEGORIES or BUSINESS_PARTNER)
"time""tag""time"Tag to use when summarizing the cashflow
"CATEGORIES""BUSINESS_PARTNERS""CATEGORIES"Use the usual tags ("sub") or their parents ("main"). Only relevant if tag=CATEGORIES
"sub""main""sub"Exclude savings and investments related transactions
falsetrueResponses
Success, tags newly created or read from database
Contracts
Identifies recurring transactions, broadly referred to as "contracts", by analyzing the user's full transaction history across all connected accounts and banks.
It categorizes each transaction using the classification logic from the categories, insurance-types, and business-partners endpoints.
Once categorized, recurring patterns are identified, and contract-like structures are formed based on transaction frequency, amount regularity, and counterparty consistency.
The system supports a wide range of recurring transaction types, such as rent, utilities, insurance, loans, subscriptions, salary, charity, and any other repeating financial obligations and income streams.
It also includes analytical insights to help with financial forecasting and decision-making.
Key Features
-
Categorization
Includes classification data from thecategories,insurance-types, andbusiness-partnersendpoints. -
Frequency Analysis
Identifies how often transactions occur and determines recurring patterns (e.g., monthly, quarterly, annually). -
Statistical Summary
Provides metrics including mean, median, total volume, standard deviation, and growth rate. -
Temporal Data
Reports on first, latest, and predicted next occurrences of a recurring transaction pattern. -
Amount Development
Tracks amount evolution and pricing changes over time. -
Contract Details
Lists contract and customer numbers, detected from transaction descriptions. -
Non-Regular Transactions
Intelligently identifies and separates transactions that don't follow the main contract pattern but are still related to the same contract (e.g., refunds, adjustments, or one-time fees within an energy or insurance contract). -
Loan & Credit Metadata
Attempts to estimate loan metadata such as total amount, interest rate, and installment terms where applicable. -
Active Status
Indicates whether a contract is currently active based on recent transaction activity. -
Traceability
Links back to source transactions and provides chronological amount development over time.
Non-Regular Transaction Handling
Due to non-regular transactions potentially skewing calculations, several statistical attributes are provided multiple times - some including all transactions and others excluding non-regular ones.
This intelligent approach allows for flexible analysis depending on whether refunds and adjustments should be included in averages and projections.
Missing Frequency Information
The system can detect contracts even when no clear frequency is established. Frequency information may be missing for one of two reasons:
- Single Transaction Contracts: When only one transaction exists but shows clear contract indicators
- Irregular Timing: When transactions appear contract-related but have inconsistent periods or recent timing changes
For some use cases, the frequency is essential, which is why we implemented a sophisticated fallback mechanism for contracts with only a single transaction.
In such cases, the attribute periodConfidenceLevel expresses the uncertainty of the period. When this attribute is not present, the period can be treated as fully reliable.
Therefore, uncertain periods can be filtered out by excluding cases where periodConfidenceLevel is present and below 1.0.
Operations
Get contracts tags
Returns contract analysis for a provided user.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Query Parameters
Return only contracts related to insurance
falsetrueReturn only contracts related to insurance and home savings plans
falsetrueResponses
Success, tags newly created or read from database
Example response with a single telecommunications contract
Credit Attributes
Provides comprehensive credit risk assessment by analyzing financial behavior patterns, income stability, expense patterns, and creditworthiness indicators to evaluate a user's financial profile for lending decisions.
Core Financial Analysis
The system combines multiple data sources to create a holistic credit risk profile:
- Contract Analysis - Leverages the
contractsendpoint to identify recurring financial obligations and income streams - Life Stage Intelligence - Incorporates
life-stagesdata to assess life situation impact on financial stability - Asset Evaluation - Includes bank products and investment analysis to determine overall financial position
- Risk Factor Detection - Identifies payment issues, gambling behavior, and other creditworthiness indicators
Key Financial Metrics
The analysis generates comprehensive metrics across multiple financial dimensions:
Income Analysis
- Total Income - Complete monthly income assessment across all sources
- Salary Income - Regular employment income with employment length tracking
- Fixed Income - Contract-based recurring income (excluding salary)
- Variable Income - Non-contract irregular income streams
- Windfall Detection - Identifies unusually large income transactions that may skew regular patterns
Expense Analysis
- Total Spending - Complete monthly expense overview
- Fixed Spending - Contract-based recurring expenses
- Variable Spending - Non-contract discretionary spending
- Savings Behavior - Monthly savings patterns and capacity
Credit-Specific Metrics
- Active Credit Contracts - Current mortgage, financial credit, and leasing obligations
- Passive Credit Contracts - Historical credit arrangements
- Credit Card Usage - Number of active credit cards and usage patterns
- Payment Reliability - Risk indicators including return debits, reminder charges, and debt collection
Advanced Risk Assessment
Life Stage Context
Analyzes four key life domains relevant to creditworthiness:
- Labor Market Status - Employment stability and career stage
- Housing Situation - Homeownership vs. tenancy status
- Relationship Status - Marital status and household stability
- Parenthood - Family responsibilities and associated financial commitments
Financial Health Indicators
- Net Cashflow - Monthly surplus/deficit with positive cashflow ratio
- Income Stability - Employment length and contract regularity
- Risk Activities - Gambling expenses and other high-risk financial behaviors
- Payment Issues - Historical payment failures and collection activities
Statistical Analysis Window
Analysis covers a 6-month rolling window to ensure:
- Statistical relevance with sufficient transaction history
- Capture of recent financial behavior patterns
- Adjustment for seasonal variations in income and expenses
- Focus on current financial capacity rather than outdated patterns
Asset and Investment Integration
Bank Products
- Account balances and overdraft utilization
- Credit limits and drawn amounts
- Product diversification analysis
Investment Portfolio
- Investment holdings and market exposure
- Risk tolerance assessment through investment choices
- Overall asset allocation patterns
Practical Applications
- Loan Origination - Comprehensive risk assessment for loan applications
- Credit Limit Determination - Data-driven credit limit setting
- Financial Product Matching - Recommend appropriate financial products based on risk profile
- Portfolio Risk Management - Monitor existing customer credit risk changes
Related Endpoints
affordability- Provides complementary financial analysis focusing on income-to-expense ratios, discretionary income calculation, and financial capacity assessment for enhanced credit decisions
Operations
Get credit attributes tags
Returns comprehensive credit risk assessment for a provided user.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Responses
Success, tags newly created or read from database
Disposable Money
Estimates a user's currently disposable money by analyzing their financial activity within the current salary cycle, from the last salary payment up to the next expected one.
The endpoint processes transactions by categorizing them according to the categories endpoint, generating contracts from the contracts endpoint, and predicting future cashflows to provide comprehensive financial insights for the current salary period.
Key Features
-
Salary Cycle Analysis
Focuses analysis on the current salary cycle, providing relevant insights for the specific time period between salary payments. -
Multi-Source Integration
Combines transaction categorization, contract analysis, and cashflow predictions to deliver accurate disposable money estimates. -
Real-Time Calculations
Provides current financial position as well as projections for the remainder of the salary cycle. -
Fixed vs. Flexible Expenses
Distinguishes between predictable contract-based expenses (fixed) and variable spending patterns (flexible) for more accurate forecasting.
Practical Applications
This endpoint empowers users to make informed financial decisions by providing clarity on their available funds throughout the salary cycle:
- Investment Planning - Safely allocate surplus funds for investments or savings without compromising essential expenses
- Affordability Assessment - Determine whether you can make a purchase now or should wait until the next salary arrives
- Budget Optimization - Make data-driven spending decisions based on projected cashflows rather than current account balance alone
Important Notes
Salary Detection Requirement: The detection of an active salary is fundamental to this endpoint. If no salary payment can be identified, the response will be empty, even if other regular income exists.
Operations
Get disposable money tag
Returns disposable money analysis based on salary cycle and spending patterns for a provided user.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Responses
Success, tag newly created or read from database
Example with disposable money information, active salary detected.
Life
Analyzes a user's life journey by detecting both current life stages and significant life events through comprehensive transaction analysis.
The following two endpoints provide complementary perspectives on a user's personal and financial development:
- Life Stages (
/life/stages/) - Identifies current states and phases across four key life domains - Life Events (
/life/events/) - Detects significant transitions and milestones with historical dates
Life Stages
Life stages represent ongoing states or phases in a user's life, detected through contract analysis and transaction patterns.
The analysis covers four essential domains:
- Labour Market - Professional and academic career status
- Parenthood - Family status and presence of children
- Housing - Ownership and rental arrangements for accommodation
- Savings - Retirement preparation and savings activities
Life Events
Life events capture significant moments of change or transition in a user's life.
These are time-specific occurrences that often mark the beginning or end of a life stage.
- Career Milestones - First employment, job changes, career transitions
- Housing Changes - First apartment, relocations, homeowner-ship
- Family Events - Marriage, birth of children, family changes
- Financial Transitions - Major income changes, retirement events
Key Differences
- Life Stages focus on current status - "What is the user's situation now?"
- Life Events focus on historical transitions - "When did significant changes occur?"
- Complementary Insights - Together they provide a complete picture of life progression
Practical Applications
- Financial Planning - Align products and services with life phase and recent changes
- Risk Assessment - Understand stability vs. transition periods in user's life
- Personalized Offers - Target recommendations based on both current needs and recent events
- Customer Journey Mapping - Track progression through different life phases over time
Get life events tags
Returns the life events for a provided user.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Responses
Success, tags newly created or read from database
Sales Triggers
Identifies sales opportunities by analyzing a user's financial profile, life events, and insurance gaps to detect when they may be receptive to specific financial products or services.
This endpoint leverages data from the contracts, life-events, and life-stages endpoints to identify optimal moments for financial product recommendations.
By analyzing patterns in income, expenses, life transitions, and insurance coverage, it determines when users are most likely to need and purchase financial products.
How Detection Works
The endpoint analyzes user data across multiple dimensions to identify sales opportunities:
- Insurance Gap Analysis - Detects missing essential insurance products (liability, occupational disability, private health insurance)
- Life Event Recognition - Identifies significant life changes that typically drive financial product needs
- Financial Pattern Analysis - Recognizes income increases, savings potential, and windfall events
- Behavioral Triggers - Combines multiple indicators to determine optimal sales timing
Sales Trigger Categories
Missing Insurance Products:
- Private Liability Insurance - User lacks basic liability coverage
- Occupational Disability Insurance - Missing income protection for work-related disabilities
- Private Health Insurance - Absent private health coverage (triggered only for high earners €3,200+ monthly)
Life Event Triggers:
- First Apartment - User has moved to their first independent residence
- New Apartment - User has relocated, indicating potential insurance updates needed
- First Employment - User has entered the workforce for the first time
- New Employment - User has changed jobs, potentially affecting insurance needs
- First Child - User has become a parent, creating new protection needs
Financial Opportunity Triggers:
- Salary Increase - User has received a significant pay raise, increasing purchasing power
- Savings Potential - User demonstrates consistent ability to save money over time
- Large Income Event - User has received substantial one-time income (2x+ average monthly income)
Practical Applications
This endpoint enables financial institutions and advisors to:
- Personalized Marketing - Target users with relevant product offers at optimal times
- Needs-Based Selling - Identify genuine product gaps rather than generic sales approaches
- Lifecycle Management - Align product recommendations with natural life transitions
- Risk Assessment - Understand which users may urgently need certain protections
Flexible Configuration
The sales trigger system is highly adaptable to specific business needs and can be extended significantly:
- Customizable Thresholds - All detection parameters can be adjusted (income thresholds, time windows, savings requirements, etc.)
- New Trigger Development - Additional sales triggers can be created for specific products, market segments, or business strategies
- Industry-Specific Adaptations - Triggers can be tailored for different financial sectors (banking, insurance, investment, etc.)
- Advanced Logic - Complex multi-factor triggers combining various life events, financial patterns, and behavioral indicators can be implemented
This foundation provides extensive scalability for sophisticated sales intelligence systems tailored to unique business requirements.
To get a full list of sales triggers, use:
GET /tags/v1/tags/tag-trees/5/tag-tree-items/
Operations
Get sales triggers tags
Returns sales triggers analysis for a provided user.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Query Parameters
Sales trigger savings potential: Threshold amount
1002505001000250Sales trigger salary raise: Increase threshold
0.10.20.250.2Responses
Success, tags newly created or read from database
Tagging Rules
Provides user-defined transaction tagging rules for automated categorization based on counterparty information.
Tagging rules allow users to create custom categorization logic that takes precedence over AI-based classification. When a transaction matches an existing tagging rule, it gets automatically tagged with the specified tag tree item instead of running through the categorization model.
Rule Structure
Each tagging rule consists of:
- Counterparty Information - Name and IBAN used to identify matching transactions
- Tag Tree Item - The classification label to apply when the rule matches (e.g.,
LIVING_GROCERIESfrom theCATEGORIEStag tree)
Rule Matching Logic
Tagging rules are applied to future transactions based on counterparty matching:
- Both counterparty name and IBAN are used for precise transaction identification
- When a transaction's counterparty information matches an existing rule, the associated tag tree item is automatically applied
- This automated tagging bypasses the standard AI categorization process, ensuring consistent classification for specific counterparties
Rule Management Constraints
Requirements: At least one of counterparty name or IBAN must exist
Uniqueness: Each user can only have one tagging rule per unique counterparty (name and IBAN combination).
Attempting to create duplicate rules for the same counterparty will overwrite the existing rule
Modification: To change the tag tree item, a new rule must be created which replaces the existing rule
Payment Service Providers: Be aware that some payment service providers, such as PayPal, themselves act as counterparties for transactions.
In such cases, the counterparty name and IBAN may not reflect the actual merchant or service provider.
Users should consider this when creating tagging rules to ensure accurate categorization.
This limitation will be addressed in future updates to further enhance the tagging rule functionality.
Integration with Tag System
Tagging rules leverage the platform's standardized tag taxonomy:
- The same Tag Trees and Tag Tree Items are used for consistent classification
- For instance, a rule can specify the Tag Tree Item with the system name
LIVING_GROCERIESfrom theCATEGORIESTag Tree
Practical Applications
- Personal Categorization - Override AI suggestions with user-preferred classifications
- Bulk Processing - Apply consistent tagging to historical and future transactions from the same counterparty
Get rules
Returns a list of all tagging rules for a specific user.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Query Parameters
ID of a tag tree. If missing, all rules are selected.
1591Responses
Success, rules read from database
Categories
Provides categorized transactions based on everyday spending types such as groceries shopping or rental payments.
The categories are a two-level hierarchy, where the first level is the main category, such as Living and the second level is a subcategory such as Clothing and Acessories. The endpoint strongly relates to the endpoint insurance-types. If an insurance type is detected, the category is set to INSURANCE and the main class of the insurance type, the division, is used as the subcategory.
To get the full list of categories, use: GET /tags/v1/tags/tag-trees/1/tag-tree-items/
Categorization Logic
We use a hybrid model, that combines a basic model and an AI model. The basic model runs first. If it cannot find a category, the AI model runs as well. If the found category has a sufficient confidence, it is returned. If the basic model yields multiple tags, the AI model runs as well. Majority voting in combination with a confidence threshold is used to determine the best fitting category.
Basic Model
The basic model searches for keywords and regular expression based substrings in note to payee, counterparty name and posting text. It includes the main categories of the insurance classifier to precisely detect insurance transactions. There are several additional steps for specific types of transactions, counterparties and categories to further improve the accuracy of this model.
Artificial Intelligence Model
The model architecture is a bidirectional recurrent neural network with long short-term memory and an attention mechanism. The samples used for training this model do not contain any user related identifiers. The training encompasses semantically-meaningful word and sub-word embeddings, pre-trained in an unsupervised setting as well as human and automatically labeled data, providing a total of more than a million training samples. Even before a human labeler processes a transaction, each transaction gets anonymized. Amounts get slightly shifted randomly and all sensible information such as names and addresses are automatically removed from all texts. With this process, data privacy is fully ensured.
Update categories tags
Applies corrections to the categorization of transactions.
Input contains the tag tree item(s) that should be used for re-categorization.
All provided tag tree items have to be valid.
If a single tag tree item is provided, all transaction tags receive this tag tree item.
If multiple tag tree items are provided, each transaction tag receives a different tag tree
item. Make sure to provide exactly as many tag tree items as transactions in this scenario.
The flag createRule creates a user specific rule that automatically categorizes this
counterparty with the provided tag tree item in all future transactions. This is a smart
solution to eradicate a recurring re-categorization process.
The flag changeExisting re-categorizes all existing transactions of the same counterparty.
The tagTreeItem(s) have to include a tagTree and have to be wrapped in tags: [].
The re-categorization relies on the systemName value of tagTreeItem and tagTree, all other
fields are ignored.
Example:
{
"tags": [
{
"tagTreeItem": {
"systemId": 67,
"systemName": "LIVING_GROCERIES",
"tagTree": {
"systemId": 1,
"systemName": "CATEGORIES"
}
}
}
]
}
To get the full list of categories, use:
GET /tags/v1/tags/tag-trees/1/tag-tree-items/
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Path Parameters
ID of the bank access
"a61f7249-7b32-42db-add0-1d4ee565aafc""0a461cd1-116b-4039-be98-543442ac4d75"ID of the bank product
"DE62500105174269735379""DE85500105178475866425"ID of the transaction
"ee8bb972-3a7d-4bb4-bfb8-a96abf4eecfd""473d3595-e08a-4e0c-a88b-ba0f77112d1b"Query Parameters
This option re-categorizes all existing transactions with this counterparty according to the provided category
falsetruefalseThis option creates a rule for this counterparty. All future transactions with this counterparty will be categorized according to the provided category.
falsetruefalseRequest Body
Responses
Request fulfilled, nothing follows
Business Partners
Identifies normalized business partners and returns detailed information such as address and website.
A business partner is the financial entity or individual that provides the good or service that the transaction is related to. It differs from the payment handler or the bank.
For instance, if you pay your rent, the business partner is your landlord or property management company, not the bank that processes the payment.
This includes private individuals - for example, when receiving rent from a tenant or paying rent to a private landlord.
How Detection Works
The detection uses sophisticated matching based on multiple data points including keywords, regular expressions, IBAN numbers, Creditor IDs, and more.
This ensures accurate identification across various transaction formats, even when the same business partner appears with different names or abbreviations across transactions.
Example: All of the following data points match to the same business partner:
- Creditor ID:
DE07ZZZ00000063475 - Keywords:
Allianz Lebensvers.AGorAllianz LV - IBAN:
DE77700202700062328142 - Regular Expression:
ALLIANZ LEBEN331.143.774
These are all normalized to the tag tree item with system name Allianz Lebensversicherungs-AG and the human-readable display name Allianz Lebensversicherung.
Practical Applications
This endpoint is particularly valuable when displaying counterparty information in user interfaces. The raw counterparty name (gegenkontoInhaber) from transaction data often has limitations:
- Not normalized: Same business partner may appear with different names or abbreviations
- Payment service providers: May show intermediaries like
PayPalinstead of the actual merchant - Missing information: Credit card transactions and other payment methods may have empty or incomplete counterparty fields
- Poor readability: Technical names or codes that aren't user-friendly
Business partner detection solves these issues by providing consistent, machine and human-readable names, IDs and additional information.
Database & Integration
Our database contains extensive information about business partners including their categories, industries, and sectors, which we directly leverage in other endpoints like categories and insurance-types.
For instance, if the business partner Rewe is detected, we automatically classify the transaction as Groceries in categories because it's a grocery store chain in Germany, or if the business partner CosmosDirekt is detected, we immediately classify the transaction as insurance-related in insurance-types because it's an insurance company.
We continuously improve and extend our database with more business partners and more detailed information and updates.
Missing and Unknown Business Partners
Since we are returning a business partner for each transaction, if no business partner from our database is detected, we use the tag tree item with the system name UNKNOWN.
This is common for private individuals and businesses not yet in our database, as well as transactions without sufficient information to identify a business partner.
To get a full list of business partners, use:
GET /tags/v1/tags/tag-trees/3/tag-tree-items/
Get business partners tags
Returns transactions with business partner information for a provided bank product.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Path Parameters
ID of the bank access
"a61f7249-7b32-42db-add0-1d4ee565aafc""0a461cd1-116b-4039-be98-543442ac4d75"ID of the bank product
"DE62500105174269735379""DE85500105178475866425"Responses
Success, tags newly created or read from database
Freelancer Categories
Gives detailed freelancer transactions categories in accordance with the Einnahmenüberschussrechnung (EÜR).
This endpoint provides specialized categorization for freelancers and self-employed individuals, focusing on tax-relevant categories that align with German tax reporting requirements. The categories are specifically designed to help with expense tracking and tax preparation.
The endpoint supports the same hierarchical categorization structure as the main categories endpoint but with a focus on business-related expenses and income streams relevant to freelancers.
To get a full list of freelancer categories, use:
GET /tags/v1/tags/tag-trees/4/tag-tree-items/
Get freelancer categories tags
Returns freelancer-specific categorized transactions for a provided bank product.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Path Parameters
ID of the bank access
"a61f7249-7b32-42db-add0-1d4ee565aafc""0a461cd1-116b-4039-be98-543442ac4d75"ID of the bank product
"DE62500105174269735379""DE85500105178475866425"Responses
Success, tags newly created or read from database
Insurance Types
Identifies insurance division and product in insurance-related transactions.
We use a sophisticated classification model to identify insurance types in transaction data.
The model combines pattern matching and machine learning techniques,
which allows us to detect and accurately classify insurance-related transactions.
Similar to the categories endpoint, the classes (which we call insurance types) are organized in a two-level hierarchy.
The first level is the insurance division, such as "Life", "Liability", or "Property".
The second level is the insurance product, such as
"Occupational Disability Insurance" (a subclass of "Life") or
"Pet Owner Liability Insurance" (a subclass of "Liability").
There are a few exceptions in this division and product scheme:
UNRELATEDis used for transactions that do not relate to insurance at all.
Since transactions are always tagged with a two-level hierarchy, there isUNRELATED_OTHER.OTHERis used for transactions that are insurance-related
but do not fit into any of the other classes or lack sufficient information to define the division.
Consequently, there is a subclassOTHER_OTHERand a subclass within each division, e.g.,LIFE_OTHERorLIABILITY_OTHER.
The categories endpoint is strongly related to this endpoint.
It calls this endpoint first, and if the category is not UNRELATED, it uses INSURANCE as the first level and the division as the second level.
To get a full list of insurance types, use:
GET /tags/v1/tags/tag-trees/2/tag-tree-items/
Get insurance types tags
Returns insurance division and product classification for a provided bank product.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Path Parameters
ID of the bank access
"a61f7249-7b32-42db-add0-1d4ee565aafc""0a461cd1-116b-4039-be98-543442ac4d75"ID of the bank product
"DE62500105174269735379""DE85500105178475866425"Responses
Success, tags newly created or read from database
Tags
Provides access to the foundational taxonomy system that powers classification across all AI endpoints.
The Tags system serves as the central repository for hierarchical classification vocabularies used throughout the platform.
Tag Tree & Tag Tree Item
The system is built around two fundamental concepts:
- Tag Trees - Versioned classification hierarchies that represent specific business domains (e.g., spending categories, insurance types, business partners)
- Tag Tree Items - Individual classification labels within each hierarchy, forming the leaves of the taxonomy tree
Data Structure
- System Name - Unique identifier for programmatic use (e.g.,
LIVING_GROCERIES) - System ID - Numeric identifier for mapping to customer's own naming schemes
- Display Name - Human-readable name for direct UI display (e.g., "Lebensmittel")
- Description - Detailed scope clarification (e.g., "Payments from grocery shopping")
Some Trag Tree Items contain additional metadata such as addresses, IBANs, or phone numbers, depending on the classification domain.
Example
The endpoint categories uses the Tag Tree Items, such as the one with the system name LIVING_GROCERIES, from the Tag Tree with the system name CATEGORIES to classify transactions.
Tag Instance Architecture
All classification endpoints follow a consistent tag instance pattern:
- Each classified transaction or entity (e.g., a user) receives tag instances linking back to specific Tag Tree Items and Tag Trees
- Tag instances maintain traceability to source data while providing standardized classification
Instance-Specific vs. Static Data:
- Tag Trees and Tag Tree Items contain only static, universal classification data
- Tag Instances contain dynamic, instance-specific information such as classification confidence scores
- Some endpoints (e.g.,
disposable-money) primarily return instance-specific calculations while maintaining Tag Tree (Item) consistency for standardized classification references
Cross-Endpoint Integration
Tag Trees and Tag Tree Items are designed for reuse across multiple endpoints, ensuring classification consistency, for instance:
categoriesendpoint: UsesCATEGORIEStag tree as primary classification sourcecontractsendpoint: IncorporatesCATEGORIES,INSURANCE_TYPES,BUSINESS_PARTNERSto build contractscredit-attributesendpoint: LeveragesCATEGORIESfor expense analysis,LIFE_STAGESfor risk assessment, and moreaffordabilityendpoint: UsesCATEGORIESto distinguish necessities from luxuries
Practical Applications
- Browse available classes before using classification endpoints
- Understand the structure and relationships within each taxonomy
- Create mappings between your own classification schemes and the platform's standardized tags
Get tag trees
Returns all available tag trees.
This endpoint can be used to get an overview of all available tag trees and a mapping of IDs and names.
Parameters
Header Parameters
ID used to track end-to-end processing of the request
"f47ac10b-58cc-4372-a567-0e02b2c3d479""6ba7b810-9dad-41d1-80b4-00c04fd430c8""550e8400-e29b-41d4-a716-446655440000"Responses
Success, tag trees read from database