Lean Technologies Balances API
The Balances API from Lean Technologies — 1 operation(s) for balances.
OpenAPI Specification
openapi: 3.1.0
info:
title: Consents Account On File Account Controls (New) Account Controls (New) Balances API
version: v0.2.3
servers:
- url: https://sandbox.leantech.me
description: Sandbox
- url: https://api2.leantech.me
description: Production
security:
- bearerAuth: []
tags:
- name: Balances
paths:
/insights/v2/assets/balances:
get:
summary: Get Cash Balances
deprecated: false
description: "The Cash Balances API provides a comprehensive view of both **Personal** or **Business** cash balances, offering insights into current, historical, and average balances. \n\nThe data in this API allows financial companies to monitor liquidity trends and assess the financial health of bank accounts over time. Additionally, it provides information on the frequency and amount of contributions. You can use these insights to evaluate repayment capacity.\n\n\nThis API is asynchronous, please read [this guide](https://docs.leantech.me/v2.0-KSA/docs/handling-asynchronous-requests) for further information on how to fetch the results.\n\n> **\"Supported for both retail and corporate accounts\"**\n> "
operationId: getBalances
tags:
- Balances
parameters:
- name: entity_id
in: query
description: The `entity_id` you're querying for.
required: true
example: bc287977-2094-3bef-82a0-bae3fe8dadfe
schema:
type: string
- name: start_date
in: query
description: The start date in UTC (in the format YYYY-MM-DD) you want to query expenses for.
required: false
example: '2024-09-01'
schema:
format: date
type: string
- name: async
in: query
description: When `true` the API will only return a `results_id` which can be fetched from the `/results` endpoint when ready.
required: false
example: 'false'
schema:
type: boolean
- name: lean-app-token
in: header
description: Your Lean app token.
required: true
example: ad0832f0-76aa-4b7b-b267-1f002d7104df
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
description: The status of the results. For async requests, initially returns PENDING.
enum:
- OK
- FAILED
- PENDING
- CONSENT_EXPIRED
type: string
results_id:
type: string
description: The ID for this result, this is used when retrieving results from the `/results` endpoint.
format: uuid
message:
description: A message describing the status of the request.
type: string
meta:
type:
- string
- 'null'
description: Optional metadata associated with the result.
timestamp:
format: date-time
description: The timestamp with timezone offset indicating when the response was generated.
type: string
status_detail:
description: Further detail on the error if status=FAILED
$ref: '#/components/schemas/StatusDetailObject'
insights:
properties:
currency:
description: The 3 Letter ISO code denominating the currency that the cashflow is provided in. This will be local currency (SAR in KSA).
type: string
examples:
- SAR
current_balance:
description: 'The current balance for the connected accounts. '
type: number
examples:
- '668782.33'
total:
$ref: '#/components/schemas/TotalBalances'
description: ''
monthly_totals:
type: array
items:
$ref: '#/components/schemas/MonthlyTotalsBalances'
balance_factors:
$ref: '#/components/schemas/balance_factors'
type: object
required:
- insights
- status
- results_id
- message
- meta
- timestamp
- status_detail
example:
status: OK
results_id: 84ea61bf-ae3f-4002-8396-ce11e37cc798
message: Data successfully retrieved
meta: null
timestamp: '2024-11-19T10:06:54.395185689Z'
status_detail: null
insights:
total:
average_balance:
currency: SAR
amount: 329558.57
initial_balance:
currency: SAR
amount: 546438.29
current_balance:
currency: SAR
amount: 680498.14
available_balance:
currency: SAR
amount: 676771.25
frequency_of_contributions: weekly
monthly_totals:
- month: 8
year: 2024
is_month_complete: true
monthly_growth_rate: 0.04
contribution_amount:
currency: SAR
amount: 36439.97
average_balance:
currency: SAR
amount: 176376.33
initial_balance:
currency: SAR
amount: 533894.93
- month: 9
year: 2024
is_month_complete: true
monthly_growth_rate: 0
contribution_amount:
currency: SAR
amount: 85588.01
average_balance:
currency: SAR
amount: 389083.36
initial_balance:
currency: SAR
amount: 592818.06
- month: 10
year: 2024
is_month_complete: true
monthly_growth_rate: 0.03
contribution_amount:
currency: SAR
amount: 5576523.99
average_balance:
currency: SAR
amount: 387400.33
initial_balance:
currency: SAR
amount: 662850.33
- month: 11
year: 2024
is_month_complete: false
monthly_growth_rate: 0
contribution_amount:
currency: SAR
amount: 120000
average_balance:
currency: SAR
amount: 35815.69
initial_balance:
currency: SAR
amount: 680498.14
balance_factors:
periods:
- period: P3M
average_balance: 28630.95
- period: P6M
average_balance: 28630.95
- period: P9M
average_balance: 28630.95
- period: P12M
average_balance: 28630.95
balance_trend: 7
balance_trend_average_month_on_month: 1817
current_balance: 36211.63
inflow_factors:
median_transaction_amount: 53.93
max_transaction_amount: 21894
min_transaction_amount: 13.31
weekday_transaction_count: 131
weekend_transaction_count: 53
average_time: 6.83
percent_greater_than_x: 33
recurring_average: 0
median_days: 4
percent_salary_transaction: 98
outflow_factors:
median_transaction_amount: 46
max_transaction_amount: 5000
min_transaction_amount: 0.08
weekday_transaction_count: 130
weekend_transaction_count: 53
average_time: 1
percent_greater_than_x: 20
recurring_average: 0
median_days: 1
spike_transactions:
- month: 11
year: 2024
amount: 15749.05
daily_net_cashflow_estimate: 138.53
headers: {}
security:
- bearer: []
components:
schemas:
balance_factors:
type: object
title: BalanceFactors
description: Balance factors analysis for cash balance insights
properties:
periods:
type: array
description: List of balance periods with their average balances
items:
type: object
properties:
period:
type: string
description: The time period in ISO 8601 duration format
enum:
- P3M
- P6M
- P9M
- P12M
examples:
- P3M
average_balance:
type: number
description: The average balance for the period
format: decimal
examples:
- 28630.95
required:
- period
- average_balance
balance_trend_average_month_on_month:
type: number
description: Average month-over-month balance trend percentage
format: decimal
examples:
- 1817
current_balance:
type: number
description: Current balance amount
format: decimal
examples:
- 36211.63
balance_trend:
type: integer
description: Number of times the balance increased month over month
minimum: 0
examples:
- 7
inflow_factors:
type: object
description: Analysis of credit (incoming) transactions
properties:
median_transaction_amount:
type: number
description: Median transaction amount
format: decimal
examples:
- 53.93
max_transaction_amount:
type: number
description: Maximum transaction amount
format: decimal
examples:
- 21894
min_transaction_amount:
type: number
description: Minimum transaction amount
format: decimal
examples:
- 13.31
weekday_transaction_count:
type: integer
description: Number of weekday transactions
minimum: 0
examples:
- 131
weekend_transaction_count:
type: integer
description: Number of weekend transactions
minimum: 0
examples:
- 53
average_time:
type: number
description: Average time between transactions in days
format: decimal
examples:
- 6.83
percent_greater_than_x:
type: number
description: Percentage of transactions greater than a threshold
format: decimal
minimum: 0
maximum: 100
examples:
- 33
recurring_average:
type: number
description: Average amount of recurring transactions
format: decimal
examples:
- 0
median_days:
type: number
description: Median number of days between transactions
format: decimal
examples:
- 4
percent_salary_transaction:
type: number
description: Percentage of transactions that are salary-related
format: decimal
minimum: 0
maximum: 100
examples:
- 98
required:
- median_transaction_amount
- max_transaction_amount
- min_transaction_amount
- weekday_transaction_count
- weekend_transaction_count
- average_time
- percent_greater_than_x
- recurring_average
- median_days
- percent_salary_transaction
outflow_factors:
type: object
description: Analysis of debit (outgoing) transactions
properties:
median_transaction_amount:
type: number
description: Median transaction amount
format: decimal
examples:
- 46
max_transaction_amount:
type: number
description: Maximum transaction amount
format: decimal
examples:
- 5000
min_transaction_amount:
type: number
description: Minimum transaction amount
format: decimal
examples:
- 0.08
weekday_transaction_count:
type: integer
description: Number of weekday transactions
minimum: 0
examples:
- 130
weekend_transaction_count:
type: integer
description: Number of weekend transactions
minimum: 0
examples:
- 53
average_time:
type: number
description: Average time between transactions in days
format: decimal
examples:
- 1
percent_greater_than_x:
type: number
description: Percentage of transactions greater than a threshold
format: decimal
minimum: 0
maximum: 100
examples:
- 20
recurring_average:
type: number
description: Average amount of recurring transactions
format: decimal
examples:
- 0
median_days:
type: number
description: Median number of days between transactions
format: decimal
examples:
- 1
spike_transactions:
type: array
description: List of transactions that are considered spikes
items:
type: object
properties:
month:
type: integer
description: Month of the spike transaction
minimum: 1
maximum: 12
examples:
- 11
year:
type: integer
description: Year of the spike transaction
examples:
- 2024
amount:
type: number
description: Amount of the spike transaction
format: decimal
examples:
- 15749.05
required:
- month
- year
- amount
required:
- median_transaction_amount
- max_transaction_amount
- min_transaction_amount
- weekday_transaction_count
- weekend_transaction_count
- average_time
- percent_greater_than_x
- recurring_average
- median_days
- spike_transactions
daily_net_cashflow_estimate:
type: number
description: Estimated daily net cash flow
format: decimal
examples:
- 138.53
required:
- periods
- balance_trend
- balance_trend_average_month_on_month
- current_balance
- inflow_factors
- outflow_factors
- daily_net_cashflow_estimate
MonthlyTotalsBalances:
type: object
properties:
month:
type: number
description: 'Number of month within the year (e.g.: January is represented as 1 and December is represented as 12).'
year:
type: number
description: Year.
is_month_complete:
type: boolean
description: Determines if Lean retrieved the data for all days for the month. This will always be true, except for the first and last month retrieved.
monthly_growth_rate:
type: number
description: The percentage of increase in the account balance each month.
format: double
contribution_amount:
description: The total amount deposited into the account each month.
$ref: '#/components/schemas/AmountObject'
average_balance:
description: The average balance for each month.
$ref: '#/components/schemas/AmountObject'
initial_balance:
description: The first balance of the month.
$ref: '#/components/schemas/AmountObject'
StatusDetailObject:
description: Status Details
type: object
properties:
granular_status_code:
description: Detailed error code
type: string
status_additional_info:
description: Further detail on the encountered error
type: string
TotalBalances:
type: object
properties:
average_balance:
description: The average balance over since start_date until today.
$ref: '#/components/schemas/AmountObject'
initial_balance:
$ref: '#/components/schemas/AmountObject'
description: The starting balance of the account since start_date
available_balance:
description: The portion of the current balance that is available for withdrawal or spending.
$ref: '#/components/schemas/AmountObject'
current_balance:
description: The total amount of money in the account at the present moment.
$ref: '#/components/schemas/AmountObject'
frequency_of_contributions:
type: string
description: How often deposits are made (daily, weekly, monthly) to the bank account.
enum:
- daily
- weekly
- monthly
AmountObject:
type: object
properties:
currency:
type: string
description: The currency in which the amount is represented.
amount:
type: number
description: The decimal amount for the transaction
description: The total amount for the category.
securitySchemes:
bearerAuth:
type: http
scheme: bearer