Summary

Cash flow is often one of the first signals of financial stress or stability. Even when income and expenses look manageable today, upcoming payments, irregular spending, and changes in balance can make it difficult to understand what the account position may look like in the near future.

Dedomena's Cash Flow Forecasting Neuron helps turn historical transaction data into a forward-looking balance forecast. It uses past movements in the account to estimate how the balance may evolve over the selected forecast horizon, together with confidence intervals that provide a range of possible outcomes instead of a single fixed value.

To use the Neuron, submit at least 3 months of transaction history. Each transaction should include the transaction date, amount, description, and account balance after the transaction. The API then returns a daily forecast that can be used to support planning, liquidity monitoring, and risk analysis.

???+ warning Forecasting is done on the fly. Dedomena AI never retains any historical or forecasted cash flow information, so you must copy the results before closing the tab or window to avoid losing the information.

The forecast horizon can be requested through the API and is automatically limited according to the historical coverage available in the submitted data.

Use Cases

Here are some key use cases for the Cash Flow Forecasting Neuron:

• Financial Planning: Help businesses and individuals anticipate future cash positions and understand whether expected balances are enough to cover upcoming obligations.

• Liquidity Management: Identify periods where available cash may be tight, allowing teams to plan transfers, financing, or expense timing in advance.

• Risk Management: Detect forecasted periods of potential negative balances and support proactive decisions before liquidity issues occur.

• Budgeting: Improve budget planning by using historical transaction behavior to estimate short-term and medium-term cash availability.

• Expense Control: Give users a clearer view of expected cash evolution, helping them identify when spending should be reduced or postponed.

• Investment Planning: Help investors and finance teams evaluate when surplus cash may be available for deposits, investments, or debt repayment.

• Loan and Credit Monitoring: Support lenders or financial platforms in assessing whether an account is likely to maintain enough liquidity over the forecast horizon.

• Treasury Operations: Assist finance teams in planning working-capital needs, payment schedules, and account funding decisions.

API & Endpoints

:material-application-brackets-outline: /cashflow

POST/v3/cashflow

This endpoint generates cashflow forecasts and defines confidence intervals based on the provided transaction history. The forecast horizon can be requested with amount_to_predict, and the API caps it automatically according to the historical coverage available in the submitted data.

Headers:

• token: available via free trial or subscription.

Query Parameters:

• amount_to_predict (integer, optional, default: 30): Number of days to forecast. The final horizon is limited by the available historical data and can range up to 365 days.

Request Body:

JSON array of transactions:

• date (string): Date of the transaction in ISO or datetime string format.

• amount (float): Transaction amount. Negative values are expenses and positive values are income.

• description (string): Description or concept of the transaction.

• balance (float): Account balance immediately after the transaction.

Request Body - JSON Array

[
 {"date": "2024-07-22",
  "amount": 200.0,
  "description": "TRANSFERENCIA DE PEDRO PEREZ PEREZ, CONCEPTO gastos tarjeta bbva.",
  "balance": 642.46},
 {"date": "2024-05-17",
  "amount": -34.65,
  "description": "COMPRA EN MERCADONA, MADRID, TARJ. :*123456",
  "balance": 607.81},

  "..."

 {"date": "2024-08-11",
  "amount": -13.4,
  "description": "PAGO MOVIL EN SUPERMERCADOS DIA, ZARAGOZA, TARJ. :*123456",
  "balance": 1230.41}
]

Response

200

{
  "forecast": [
    {
      "date": "2024-09-03",
      "balance": 311.33,
      "expenses_day_min": -136.14,
      "incomes_day_min": 0.0,
      "balance_day_min": -14.74,
      "expenses_day_max": -13.0,
      "incomes_day_max": 0.0,
      "balance_day_max": 479.15,
      "expenses_dayofweek_min": -136.14,
      "incomes_dayofweek_min": 0.0,
      "balances_dayofweek_min": -14.74,
      "expenses_dayofweek_max": 0.0,
      "incomes_dayofweek_max": 661.5,
      "balances_dayofweek_max": 854.75,
      "pred95": 350.12,
      "pred05": 301.43
    }
  ]
}

401

{
  "detail": "Invalid or missing authentication token"
}

405

{
  "detail": "Unable to generate a cashflow forecast with the provided data"
}

406

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

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 at least 3 month of transactions dataset path and needed parameters.

# Change names and types
data_request.columns = ["date", "description", "amount", "balance"] # Optional: change columns names.

# Convert to records from Pandas dataframe
data_json = data_request.sample(100).to_dict(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": "...", "amount_to_predict": 30} ## Update with the token from API tab.
response = requests.post(url="https://api.cashflow.dedomena.ai/v3/cashflow", params=payload, json=data_json)
print(response)

# Transform to Pandas dataframe the request response
response_forecast = pd.DataFrame(response.json()['forecast'])

# Check the results
response_forecast