Skip to content

Transaction Enricher

Summary

Enriching bank transactions by categorizing them into spending and income categories can provide valuable insights for both personal and business financial management. This Neuron allows you to categorize customer's (whether people or companies) bank operations in spending and income categories based on Dedomena's taxonomy, plus merchant information.

Dedomena's taxonomy consists of 92 categories: 11 related to income and 81 related to spending.

Examples of Categories:

  1. Spending Categories: Supermarket and Groceries, Taxi, VTC and Shared Mobility, Office and home supplies, Pharmacy.
  2. Income Categories: Salary and Retirement, Interest and Dividends, Sales, Incoming transfers.

Use Cases

Below some key use cases are provided:

  • Budgeting and Forecasting: Helps set and stick to budgets by tracking spending across various categories (e.g., groceries, entertainment, utilities). Assists in creating accurate budgets and financial forecasts by analyzing historical spending and income patterns.
  • Expense Tracking and Management: Enables users to monitor and analyze spending patterns, identify unnecessary expenditures, and adjust habits to save money. Helps in monitoring and controlling business expenses, identifying areas where costs can be reduced.
  • Savings Goals: Assists in setting and achieving savings goals by providing a clear view of income vs. expenses.
  • Tax Preparation: Simplifies tax filing by categorizing transactions relevant to tax deductions (e.g., charitable donations, medical expenses).
  • Debt Management: Helps in managing and prioritizing debt repayments by tracking how much is being paid towards debts versus other expenses.
  • Financial Health Monitoring: Provides a holistic view of financial health by tracking net income and categorizing spending.
  • Cash Flow Analysis: Tracks incoming and outgoing cash flows, helping businesses manage liquidity and plan for future cash needs.
  • Profitability Analysis: Enables businesses to assess the profitability of different departments or projects by categorizing revenues and expenses.
  • Tax Compliance: Simplifies tax preparation and ensures compliance by categorizing transactions according to tax regulations.
  • Audit and Reporting: Facilitates internal and external audits and financial reporting by maintaining organized and categorized transaction records.
  • Fraud Detection: Identifies unusual transactions that deviate from normal spending or income patterns, flagging potential fraudulent activity.
  • Financial Planning: Assists in long-term financial planning by providing a clear picture of income streams and spending habits.
  • Personalized Financial Advice: Enables financial advisors to provide tailored advice based on detailed transaction categorizations.
  • Automated Alerts: Sets up alerts for specific transaction categories, such as when spending exceeds a certain limit or when income is deposited.
  • Integration with Financial Tools: Enhances the functionality of financial apps and tools by providing categorized transaction data for more accurate financial analysis and advice.

Taxonomy

Please, find the Transactions Enricher Taxonomy in the Resources tab.

API & Endpoints

Access API User Interface (Swagger) (1)

The current version of this Neuron is V5.2.0.

/v5/enricher

POST /v5/enricher/{region}

This route/endpoint allows classifying a bank transaction or group of bank transactions into one of the 92 categories of Dedomena's taxonomy. It can be used to categorize a single transaction or up to 120 000 transactions in a single request.

Path Parameters:

  • region (str): select the region of transaction(s). Options: Spain.

Headers:

  • token: available via free trial or subscription.

Request Body:

A list of transactions to be classified. Each transaction should include the following fields:

  • transaction_id (str): string with a unique ID for each transaction.
  • date (datetime): datetime variable with the date of each transaction.
  • desc (str): string with a description/concept of the transaction.
  • amt (float): numerical variable with the amount of the transaction.

Transactions API

Request Body - JSON Array
[
  {
    "transaction_id": "txn-123",
    "date": "2024-10-10 10:10:10",
    "desc": "Payments to Dedomena AI",
    "amt": "-999"
  }
]
Response

200

[
  {
    "transaction_id": "txn-345",
    "pred_category": 164,
    "pred_category_name": "ATM, Cash",
    "pred_prob": 0.999999,
    "pred_category_parent": 161,
    "pred_category_parent_name": "Miscelaneous expenses",
  },
]

Description:

  • 'transaction_id': string with a unique ID for each transaction.
  • 'pred_category': numeric variable with the id of the category to which the transaction belongs.
  • 'pred_category_name': string with the name of the category to which the transaction belongs.
  • 'pred_prob': probability that the transaction belongs to the predicted category.
  • 'pred_category_parent': numeric variable with the id of the parent category to which the transaction belongs.
  • 'pred_category_parent_name': string with the name of the parent category to which the transaction belongs.

402

[
  {
  "detail": "Could not validate credentials"
  }
]

406

[
  {
    "detail": "The number of observations in the payload exceed the available quote"
  }
]

422

[
  {
    "detail": "Unprocessable Entity"
  }
]

429

[
  {
    "detail": "The maximum monthly number of calls or predictions for your account has been exceeded"
  }
]
Using Python

You can run this example from a Jupyter Notebook or Python script.

NOTE: you should replace the ... by the correct information in the following code:

import pandas as pd
import requests

# Read the data
data_request = pd.read_csv(...) ## Update with the dataset path and needed parameters.

# Change names and types
data_request.columns = ["transaction_id", "date", "desc", "amt"] # Optional: change columns names.
data_request.transaction_id = data_request.transaction_id.astype(str) # Optional: convert "transaction_id" column to string/object type
data_request.amount = data_request.amt.astype(str) # Optional: convert "amt" column to string/object type

# Convert to JSON from Pandas dataframe
data_json = data_request.sample(100).to_json(orient='records') ## Here the data is sampled by taking 100 rows from the original data set. Please modify it as per your convenience.

# Define the Payload and save the request in a response object
payload = {'token': '...', 'region':'SPAIN'} ## Update with the token from API tab.
response = requests.post(url="https://api.enricher.dedomena.ai/v5/enricher", params=payload, data=data_json)
print(response)

# Transform to Pandas dataframe the request response
enriched_data = pd.DataFrame(response.json(), 
                             columns=["transaction_id","date","desc","amt","pred_category","pred_category_name",
                             "pred_prob", "pred_category_parent","pred_category_parent_name"])

# Check the results
enriched_data
Warning

All values ​​must be passed as strings.

/v2/merchant

POST /v2/merchant

This route/endpoint allows you to extract the merchant of the bank transaction.

Path Parameters:

  • region: select the region of transaction(s). Options: Spain.

Headers:

  • token: available via free trial or subscription.

Request Body:

A list of transactions to be classified. Each transaction should include the following fields:

  • transaction_id: string with a unique ID for each transaction.
  • date: datetime variable with the date of each transaction.
  • desc: string with a description/concept of the transaction.
  • amt: numerical variable with the amount of the transaction.

Transactions API

Request Body - JSON Array
[
  {
    "transaction_id": "txn-123",
    "date": "2024-10-10 10:10:10",
    "desc": "Payments to Dedomena AI",
    "amt": "-999"
  }
]
Response

200

[
  {
    "transaction_id": "txn-123",
    "merchant": "MERCADONA"
  }
]

Description:

  • 'transaction_id': string with a unique ID for each transaction.
  • 'merchant': string with the merchant identified in the transactions.

402

[
  {
  "detail": "Could not validate credentials"
  }
]

406

[
  {
    "detail": "The number of observations in the payload exceed the available quote"
  }
]

422

[
  {
    "detail": "Unprocessable Entity"
  }
]

429

[
  {
    "detail": "The maximum monthly number of calls or predictions for your account has been exceeded"
  }
]
Using Python

You can run this example from a Jupyter Notebook or Python script.

NOTE: you should replace the ... by the correct information in the following code:

import pandas as pd
import requests

# Read the data
data_request = pd.read_csv(...) ## Update with the dataset path and needed parameters.

# Change names and types
data_request.columns = ["transaction_id", "date", "desc", "amt"] # Optional: change columns names.
data_request.transaction_id = data_request.transaction_id.astype(str) # Optional: convert "transaction_id" column to string/object type
data_request.amount = data_request.amt.astype(str) # Optional: convert "amt" column to string/object type

# Convert to JSON from Pandas dataframe
data_json = data_request.sample(100).to_json(orient='records') ## Here the data is sampled by taking 100 rows from the original data set. Please modify it as per your convenience.

# Define the Payload and save the request in a response object
payload = {'token': '...', 'region':'SPAIN'} ## Update with the token from API tab.
response = requests.post(url="https://api.enricher.dedomena.ai/v2/merchant", params=payload, data=data_json)
print(response)

# Transform to Pandas dataframe the request response
merchant_data = pd.DataFrame(response.json(), columns=["transaction_id","merchant"])

# Check the results
merchant_data
Warning

All values ​​must be passed as strings.

/metrics

POST /metrics

This route/endpoint allows you to view the quota available for API calls and predictions, as seen in the Metrics tab.

headers:

  • token: available via free trial or subscription.

Transactions API

Response

200

{
  "MonthlyRequestsLimit": 10,
  "CurrentRequestsCount": 2,
  "MonthlyOutputsLimit": 10,
  "CurrentOutputsCount": 5
}

Description:

  • 'MonthlyRequestsLimit': Limit of available requests/calls according to the contracted plan per month.
  • 'CurrentRequestsCount': Number of requests/calls consumed in the current period.
  • 'MonthlyOutputsLimit': Limit of available outputs/predictions according to the contracted plan per month.
  • 'CurrentOutputsCount': Number of outputs/predictions consumed in the current period.

402

[
  {
  "detail": "Could not validate credentials"
  }
]

422

[
  {
    "detail": "Unprocessable Entity"
  }
]

AI Model Metrics

Below you can find common calculated metrics to measure AI and ML model performance. Best practices, such as hold-out methods using test and validation data sets, were followed to compute the resulting metrics.

Accuracy
F1-Score
Recall
0.96 0.98 0.96