Convert service (V3)

The Convert Service provides structured and normalized transaction data as delivered by banks. This service can be expanded with optional enrichment features, offering additional insights such as classifying transactions into categories, assigning economic activity codes (e.g., NACE or SBI), identifying transaction properties, and retrieving detailed counterparty information.

All enrichment functions are optional and can be customized to meet specific needs, allowing for advanced categorization and enhanced data relevance. Internal tools and algorithms further improve the accuracy of these enrichments.

Key Functionalities of the Convert Service

1. Parsing, Structuring, and Normalizing
   The service includes functionality for parsing raw transaction data, structuring it into a standardized format, and normalizing the information to ensure consistency and reliability across different data sources.

2. Categorization of Transactions
   Transactions are categorized into predefined groups to provide insight into spending behavior.

3. NACE or SBI Codes for Economic Activities
   Integration of NACE (Nomenclature of Economic Activities) or SBI (Standard Business Identifier) codes to classify economic activities related to each transaction.

4. Transaction Properties Extraction
   Extraction of key properties from transactions to facilitate detailed analysis and reporting.

5. Counterparty Information
   Provision of detailed information regarding counterparties involved in transactions.

6. Recurrence Integration
   Identification and integration of recurring transactions for better financial planning and tracking.

7. Machine Learning Integration
   Utilization of machine learning algorithms to enhance categorization accuracy and predictive analytics.

8. Transaction Dates Handling
   Management of transaction dates to ensure accurate time-series analysis and reporting.

Parsing, Structuring, and Normalizing

The Convert Service uses methods for parsing, structuring, and normalizing transaction data to transform raw information into a consistent and usable format. This process is essential for accurate analysis and reporting.

Parsing

• Definition: Parsing involves breaking down raw data into smaller components to identify and extract relevant information.
• Functionality: The service handles various data formats, including CSV, JSON, XML, and other structured and unstructured formats, ensuring flexibility in data ingestion.
• Output: Parsed data includes key elements such as transaction amounts, dates, descriptions, and counterpart details, which are necessary for further processing.

Structuring

• Definition: Structuring refers to organizing parsed data into a predefined schema, allowing for uniformity and ease of access.
• Functionality: The Convert Service organizes transaction data according to industry standards and internal guidelines, categorizing it into clearly defined fields (e.g., amounts, dates, descriptions).
• Output: This structured format facilitates quick retrieval and manipulation of data, making it easier to analyze spending patterns and trends.

Normalizing

• Definition: Normalizing is the process of adjusting data to ensure consistency across various datasets, particularly when integrating information from multiple sources.
• Functionality: The Convert Service standardizes data entries, such as currency formats, date formats, and naming conventions, to eliminate discrepancies and ensure comparability.
• Output: Normalized data provides a consistent foundation for accurate reporting, enabling users to derive meaningful insights and make informed financial decisions.

By incorporating parsing, structuring, and normalizing capabilities, the Convert Service improves the quality and usability of transaction data, leading to better financial oversight and analysis.

Categorization of Transactions

Transactions are organized into predefined categories according to a standardized scheme. This system is designed to provide insights into spending behavior and financial activities.

• Main Sections: These are broad categories that represent general types of expenses, such as "Household Expenses" (HUISHOUDELIJKE UITGAVEN) and "Transport" (VERVOER).

• Categories: These are specific classifications of transactions that fall under main sections. For example, under "Household Expenses," you may find categories like "Food and Snacks," "Personal Care," and "Pets."

• Groups: Groups serve as contextual additions to the categories, providing further classification but are not a hierarchical part of the categories.

Nibud

Nibud provides a framework that can be used to aggregate categories into less detailed groupings. This allows for a more generalized understanding of spending patterns without altering the detailed categorization scheme.

Customization

The category scheme can be personalized to meet the specific needs of a business or application, enabling the inclusion of various categories specifically designed for distinct purposes, ensuring the categorization remains relevant and practical for different use cases.

NACE Rev. 2 or SBI Codes

The NACE (Nomenclature statistique des Activités économiques dans la Communauté Européenne) codes provide standardized classifications of economic activities for companies, offering insights into the nature of a business entity. In the Dutch context, the SBI (Standard Industrial Classifications) code is specifically used.

• NACE Codes: Used across the European Union to classify business activities.

• SBI Codes: A derivative of the NACE code, specific to the Netherlands, and utilized by the Central Bureau of Statistics (CBS) and the Chamber of Commerce (KvK).

In the Netherlands, every company registered with the Chamber of Commerce (KvK) is assigned an SBI code, which facilitates the classification of business activities and enables comparisons across different companies or sectors.

For more information, see: http://ec.europa.eu/eurostat/web/nace-rev2/correspondence_tables

Transaction Properties Extraction

The Convert Service is capable of extracting various properties related to a transaction. These properties provide additional context and are added to a transaction, categorized into:

• Personal Details: Information like the postal code or house number associated with the transaction.

• Relational Properties: Details such as the customer number at the counterparty (the company or individual involved in the transaction).

• Transaction-bound Properties: Specific details tied to the transaction itself, including invoice numbers, policy numbers, or license plate numbers (for vehicle-related transactions).

See Properties and transaction types for an overview of all the properties that can be detected.

Information on the counterpart

For transactions involving a business as the counterparty (i.e., the recipient or initiator of the transaction), the Convert Service can provide a variety of additional information about that business, including:

• Business Name and Address

• Geographic Location (GPS Coordinates)

• Judicial Information (limited)

• Contact Information (website, phone number, email)

• Business Activities (optional)

The service distinguishes between financial counterparts (e.g., payment providers) and substantive counterparts (the actual business involved in the transaction). If both are available, the substantive counterpart is used for categorization and analysis.

Recurrence Integration

The Convert Service supports the identification of recurring transactions, which can be enabled on /convert by using the IncludeRecurrence flag in the headers of the request. When set to true, the recurrence algorithm will be executed on the given transaction batch. This algorithm will only run if it is included in your contract.

When the IncludeRecurrence flag is enabled, it will add three properties to each recurrent transaction:

• RecurrenceSequence: Indicates the sequence of the recurrence.

• RecurrenceInterval: A number that states how often the transaction occurs in a given time period.

• RecurrenceType: Defines the type of recurrence. The possible values are:

  • 0 => None
  • 1 => Second
  • 2 => Minute
  • 3 => Hour
  • 4 => Day
  • 5 => Week
  • 6 => Month
  • 7 => Quarter
  • 8 => Semester
  • 9 => Year

For example, if a transaction has a RecurrenceInterval of 3 and a RecurrenceType of 6, it means the transaction recurs every 3 months.

Machine Learning Integration

Machine learning can be enabled on /convert by using the IncludeMachineLearning flag in the headers of the request.

When set to true, the Machine Learning (ML) API will be called on the given transaction batch.

The Machine Learning algorithm will only be executed if you have this included in your contract.

When the IncludeMachineLearning flag is enabled, it will add 2 properties to each transaction:

• MlCategory: The ID of the category that the Machine Learning API returned.

• MlProbability: A confidence score ranging from 0 to 1, indicating how certain the Machine Learning API is about the categorization (e.g., 1 = 100% certain).

This integration enhances transaction categorization by providing improved accuracy, especially in cases where traditional rule-based methods may not be as effective.

Handling of Transaction Dates

Transaction dates are essential for understanding the timing of financial activities. The Convert Service extracts three key dates from the PSD2 file format:

1. bookDate: This is the date when the transaction is officially recorded in the bank's system. It is directly provided by the bank in the PSD2 file.

2. interestDate: This date represents when the transaction begins to accrue interest. Like the book date, it is also sourced from the PSD2 file when available.

3. parsedDate: If the bank does not provide the transaction date explicitly, the service attempts to parse the date from the transaction description. This date is only present if the parsing is successful.

In some cases, banks may provide the exact time of the transaction along with the dates. If this time information is available and successfully parsed, it will be included in the transaction data to offer a more precise timestamp.

This feature ensures that all relevant time-related information is captured, enriching the output and facilitating further analysis.

Convert Service Output Formats

The Convert service supports multiple output formats. By setting the Accept header, you can specify the format of the response:

• JSON (default): Standard format for API responses.
• CSV: Useful for spreadsheet data and tabular analysis.
• PDF: A formatted, print-friendly version of the data.

Setting the Accept Header

To receive a specific format, include the Accept header in your request with one of the following values:

• For JSON: application/json
• For CSV: text/csv
• For PDF: application/pdf

For more information, refer to the MDN documentation on the Accept header.

Calling the Convert service

The Convert Service can be called programmatically via API, and its functionality is governed by a set of input parameters that include flags for enabling or disabling specific features (e.g., recurrence and machine learning). Each batch of transactions processed by the service is enriched based on the chosen options.
Please refer to the API reference for the Convert service for all technical details on how to call this service.

Important input variables

Input Variable	Description
ConsentCollectionID	Identifier for consent-based access to transaction data, unique to each collection.
File (binary data)	Uploaded bank file containing transaction data, required if ConsentCollectionID is not provided.
IncludePending	Boolean to include pending transactions in the response (default is false).
IncludeRecurrence	Boolean to activate recurrence detection, useful for identifying repeating transaction patterns.
IncludeMachineLearning	Boolean to enable machine learning-based categorization for more precise classification.
KvK	Chamber of Commerce identifier for business categorization.
SBI	Business activity classification code; default SBI from the Chamber of Commerce is used if not specified.
Businesses	JSON input for specifying additional business categorization information.
Virtuals	JSON for defining IBANs of virtual accounts, helping treat multiple accounts as part of the transaction batch.

Output fields

Output Field	Description
format	Indicates the format of the response (e.g., "string").
from	The start date of the transactions returned, in ISO 8601 format.
to	The end date of the transactions returned, in ISO 8601 format.
accounts	An array of account objects, each containing details about the account transactions.
businesses	An array of business objects associated with the transactions, providing business details.
groups	An array of group objects that categorize the transactions or accounts.
categories	An array of category objects used for classifying the transactions.
naces	An array of NACE (economic activity) codes associated with the transactions.
requestId	A unique identifier for the API request, useful for tracking and logging purposes.
conversationId	A unique identifier for the conversation, used to group related API calls or interactions.