Lean Technologies Behavioral Insights (New) API
The Behavioral Insights (New) API from Lean Technologies — 1 operation(s) for behavioral insights (new).
OpenAPI Specification
openapi: 3.1.0
info:
title: Consents Account On File Account Controls (New) Account Controls (New) Behavioral Insights (New) API
version: v0.2.3
servers:
- url: https://sandbox.leantech.me
description: Sandbox
- url: https://api2.leantech.me
description: Production
security:
- bearerAuth: []
tags:
- name: Behavioral Insights (New)
paths:
/insights/v3/behaviors:
servers: []
get:
operationId: getBehavioralInsights
summary: Get Behavioral Insights
description: Enriches debit transactions with category, merchant, and location data, returning aggregated spend analytics by category, merchant, and geography.
parameters:
- name: entity_id
in: query
description: The `entity_id` you're querying for.
required: true
schema:
type: string
format: uuid
- name: start_date
in: query
description: The start date in UTC (in the format YYYY-MM-DD) of the analysis window. When omitted, defaults to the earliest debit transaction available for the entity.
required: false
schema:
type: string
format: date
x-field-extra-annotation: '@jakarta.validation.constraints.PastOrPresent'
- name: end_date
in: query
description: The end date in UTC (in the format YYYY-MM-DD) of the analysis window (inclusive — transactions on this date are included). When omitted, defaults to the current time.
required: false
schema:
type: string
format: date
x-field-extra-annotation: '@jakarta.validation.constraints.PastOrPresent'
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- properties:
insights:
$ref: '#/components/schemas/BehaviorsPayload'
type:
$ref: '#/components/schemas/InsightsResultType'
type: object
examples:
Get_BehavioralInsights_UAE_2:
summary: Successful get behavioral insights - UAE
value:
status: OK
results_id: d982e1fd-aaf0-41fe-9f11-a4f67f4dc918
message: Data successfully retrieved
timestamp: '2026-01-08T12:07:48Z'
type: behaviors
insights:
behaviors:
by_category:
detected_primary_category_count: 3
detected_secondary_category_count: 3
transaction_count: 6
breakdown:
- primary_category: Retail
secondary_category: Clothing
merchant_names:
- Zara
merchant_count: 1
total_amount:
currency: AED
amount: 200
average_transaction_amount:
currency: AED
amount: 200
transaction_count: 1
average_monthly_transactions: 0.06
average_monthly_transactions_active: 1
average_monthly_amount:
currency: AED
amount: 11.76
average_monthly_amount_active:
currency: AED
amount: 200
first_transaction_date: '2025-03-10T00:00:00Z'
last_transaction_date: '2025-03-10T00:00:00Z'
active_months: 1
- primary_category: Transportation
secondary_category: Fuel
merchant_names:
- Shell
merchant_count: 1
total_amount:
currency: AED
amount: 220
average_transaction_amount:
currency: AED
amount: 110
transaction_count: 2
average_monthly_transactions: 0.12
average_monthly_transactions_active: 1
average_monthly_amount:
currency: AED
amount: 12.94
average_monthly_amount_active:
currency: AED
amount: 110
first_transaction_date: '2025-01-20T00:00:00Z'
last_transaction_date: '2025-02-20T00:00:00Z'
active_months: 2
- primary_category: Food & Dining
secondary_category: Restaurants
merchant_names:
- Albaik
merchant_count: 1
total_amount:
currency: AED
amount: 110
average_transaction_amount:
currency: AED
amount: 55
transaction_count: 2
average_monthly_transactions: 0.12
average_monthly_transactions_active: 1
average_monthly_amount:
currency: AED
amount: 6.47
average_monthly_amount_active:
currency: AED
amount: 55
first_transaction_date: '2025-01-10T00:00:00Z'
last_transaction_date: '2025-02-10T00:00:00Z'
active_months: 2
by_merchant:
detected_merchant_count: 3
transaction_count: 6
breakdown:
- merchant_name: Albaik
transaction_count: 2
total_amount:
currency: AED
amount: 110
average_transaction_amount:
currency: AED
amount: 55
average_monthly_transactions: 0.12
average_monthly_transactions_active: 1
average_monthly_amount:
currency: AED
amount: 6.47
average_monthly_amount_active:
currency: AED
amount: 55
first_transaction_date: '2025-01-10T00:00:00Z'
last_transaction_date: '2025-02-10T00:00:00Z'
active_months: 2
- merchant_name: Zara
transaction_count: 1
total_amount:
currency: AED
amount: 200
average_transaction_amount:
currency: AED
amount: 200
average_monthly_transactions: 0.06
average_monthly_transactions_active: 1
average_monthly_amount:
currency: AED
amount: 11.76
average_monthly_amount_active:
currency: AED
amount: 200
first_transaction_date: '2025-03-10T00:00:00Z'
last_transaction_date: '2025-03-10T00:00:00Z'
active_months: 1
- merchant_name: Shell
transaction_count: 2
total_amount:
currency: AED
amount: 220
average_transaction_amount:
currency: AED
amount: 110
average_monthly_transactions: 0.12
average_monthly_transactions_active: 1
average_monthly_amount:
currency: AED
amount: 12.94
average_monthly_amount_active:
currency: AED
amount: 110
first_transaction_date: '2025-01-20T00:00:00Z'
last_transaction_date: '2025-02-20T00:00:00Z'
active_months: 2
by_location:
detected_location_count: 2
transaction_count: 6
breakdown:
- location: Riyadh
transaction_count: 3
total_amount:
currency: AED
amount: 350
average_transaction_amount:
currency: AED
amount: 116.67
average_monthly_transactions: 0.18
average_monthly_transactions_active: 1.5
average_monthly_amount:
currency: AED
amount: 20.59
average_monthly_amount_active:
currency: AED
amount: 175
first_transaction_date: '2025-01-10T00:00:00Z'
last_transaction_date: '2025-03-10T00:00:00Z'
active_months: 2
- location: Jeddah
transaction_count: 2
total_amount:
currency: AED
amount: 180
average_transaction_amount:
currency: AED
amount: 90
average_monthly_transactions: 0.12
average_monthly_transactions_active: 2
average_monthly_amount:
currency: AED
amount: 10.59
average_monthly_amount_active:
currency: AED
amount: 180
first_transaction_date: '2025-02-10T00:00:00Z'
last_transaction_date: '2025-02-20T00:00:00Z'
active_months: 1
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsResult'
examples:
InvalidParametersExample:
$ref: '#/components/examples/InsightsInvalidParametersExample'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsResult'
examples:
UserPermissionsNotGrantedExample:
$ref: '#/components/examples/InsightsUserPermissionsNotGrantedExample'
ConsentExpiredExample:
$ref: '#/components/examples/InsightsConsentExpiredExample'
TransactionRangeNotGrantedExample:
$ref: '#/components/examples/InsightsTransactionRangeNotGrantedExample'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsResult'
examples:
UnknownEntityExample:
$ref: '#/components/examples/InsightsUnknownEntityExample'
DataNotFoundExample:
$ref: '#/components/examples/InsightsDataNotFoundExample'
'408':
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsResult'
examples:
TimeoutExample:
$ref: '#/components/examples/InsightsTimeoutExample'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InsightsResult'
examples:
InternalServerErrorExample:
$ref: '#/components/examples/InsightsInternalServerErrorExample'
tags:
- Behavioral Insights (New)
components:
schemas:
CashFlowNet:
type: object
properties:
overall_amount:
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
net_cashflow:
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
CashBalanceTotal:
type: object
properties:
average_balance:
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
initial_balance:
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
current_balance:
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
available_balance:
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
frequency_of_contributions:
description: How often deposits are made to the account
type: string
CreditObligationsV2:
description: Lender-oriented view of credit activity, split into repayments and disbursements.
type: object
properties:
repayments:
description: Aggregated credit repayment activity (e.g. BNPL instalments, loan repayments).
allOf:
- $ref: '#/components/schemas/CreditObligationsRepayments'
disbursements:
description: Aggregated credit disbursement activity (loans received).
allOf:
- $ref: '#/components/schemas/CreditObligationsDisbursements'
additionalProperties: false
required:
- repayments
- disbursements
CreditDebitBehaviour:
type: object
properties:
periods:
type: array
items:
$ref: '#/components/schemas/CreditDebitBehaviourPeriod'
required:
- periods
CashflowPatterns:
description: Cashflow pattern analysis results.
type: object
properties:
cashflow_patterns:
description: List of identified cashflow patterns.
type: array
items:
$ref: '#/components/schemas/CashflowPattern'
required:
- cashflow_patterns
CreditAssessmentComputedIndicators:
description: Derived financial indicators used in credit assessment decisions.
type: object
properties:
average_monthly_net_cashflow:
description: Average monthly net cashflow (weighted income minus total expenses).
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
dbr:
description: monthly credit obligations ÷ weighted monthly income, with the lender's configurable ceiling (default 0.45) and the maximum new installment affordable before that ceiling
allOf:
- $ref: '#/components/schemas/CreditAssessmentRatioIndicator'
affordability:
description: (essential expenses + credit obligations) ÷ weighted monthly income over configured essential categories, with the lender's configurable ceiling (default 0.70) and the maximum new installment affordable before that ceiling.
allOf:
- $ref: '#/components/schemas/CreditAssessmentRatioIndicator'
additionalProperties: false
required:
- average_monthly_net_cashflow
- dbr
- affordability
CurrencyAmount:
type: object
properties:
currency:
$ref: '#/components/schemas/Currency'
amount:
description: The amount of money in the currency specified.
type: number
required:
- currency
- amount
InsightsResultType:
description: type of insight
type: string
enum:
- income
- employment
- cashflow
- credits-obligations
- non-credits-obligations
- expenses
- cash-balances
- freelancer-cashflow
- behaviors
- cashflow-patterns
- credit-assessments
- account-controls
- credit-obligations
NonCreditObligationsMonthlyAmount:
type: object
properties:
month:
description: The month name (e.g., "September", "October")
type: string
amount:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
Result:
type: object
properties:
status:
$ref: '#/components/schemas/ResultStatus'
results_id:
description: The unique identifier for the request
type: string
format: uuid
message:
description: A message describing the status of the request
type: string
meta:
description: Meta information about the request
type:
- object
- 'null'
additionalProperties:
type: string
timestamp:
description: The datetime of when the request was made
type: string
format: date-time
status_detail:
description: Additional information about the status
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/StatusDetail'
required:
- status
- results_id
- message
- timestamp
CashFlowCategoryAmountCount:
type: object
properties:
category:
description: The category of the cash flow
type: string
amount:
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
count:
description: The count of transactions in this category
type: integer
EmploymentDetails:
type: object
properties:
bank_employer_name:
description: The name of the employer as it appears in bank transaction descriptions. This is the raw employer name extracted directly from salary payment transaction records.
type:
- string
- 'null'
matched_reference_employer:
description: Information about the verified employer entity that matched with the bank employer name. Value will be NULL if no matching stored in our database
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/EmployerDetails'
required:
- name
- cr_number
salary_consistent:
description: Boolean indicator that determines if the salary payments from this employer follow a consistent pattern. true indicates stable payment patterns, while false indicates irregularity. This is calculated by comparing both date and amount variances against predefined thresholds (typically 5 days for dates and 1000 currency units for amounts).
type:
- boolean
- 'null'
salary_date_variance:
description: A statistical measure of the variability in the timing of salary payments, expressed as the standard deviation of intervals (in days) between consecutive salary payments. Lower values indicate more consistent payment timing. A value of 0 means all payments were made at exactly the same interval.
type:
- number
- 'null'
format: double
x-java-type: java.math.BigDecimal
salary_amount_variance:
description: A statistical measure of the variability in salary payment amounts, expressed as the standard deviation of payment amounts. Lower values indicate more consistent payment amounts. A value of 0 means all payments were exactly the same amount.
type:
- number
- 'null'
format: double
x-java-type: java.math.BigDecimal
first_salary_date:
description: The timestamp of the earliest detected salary payment from this employer. This indicates when the employment relationship began or when the earliest available transaction record starts.
type:
- string
- 'null'
format: date-time
x-java-type: java.time.Instant
required:
- bank_employer_name
- matched_reference_employer
- salary_consistent
- salary_date_variance
- salary_amount_variance
- first_salary_date
CreditObligationsRepayments:
description: Repayment aggregates and breakdown by lender_name, credit_type.
type: object
properties:
overall:
description: Overall repayment summary across all lenders.
allOf:
- $ref: '#/components/schemas/CreditObligationsOverall'
breakdown:
description: One entry per lender that received repayments.
type: array
items:
$ref: '#/components/schemas/CreditObligationsRepaymentBreakdown'
additionalProperties: false
required:
- overall
- breakdown
CreditAssessmentOtherIncomeBreakdownItem:
description: A single non-employment income source with its contribution details.
type: object
properties:
source:
description: The income source type.
allOf:
- $ref: '#/components/schemas/IncomeSourceType'
total_amount:
description: Total amount from this income source over the analysis period.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
average_monthly_amount:
description: Average monthly amount from this income source.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
contribution_factor:
description: Factor applied to weight this income source in the overall income calculation. Range is 0.0 to 1.0.
type: number
contributed_average_monthly_income:
description: Weighted average monthly amount after applying the contribution factor.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
additionalProperties: false
required:
- source
- total_amount
- average_monthly_amount
- contribution_factor
- contributed_average_monthly_income
CurrentCreditCardsBalance:
type: object
properties:
amount:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
BehavioralMerchantBreakdown:
description: Aggregate stats for one merchant.
type: object
properties:
merchant_name:
description: Merchant name.
type: string
transaction_count:
description: Number of transactions with this merchant.
type: integer
total_amount:
description: Total spend with this merchant.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
average_transaction_amount:
description: Average transaction amount with this merchant.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
average_monthly_transactions:
description: Average monthly transaction count for this merchant across the full analysis window.
type: number
format: double
x-java-type: java.math.BigDecimal
average_monthly_transactions_active:
description: Average monthly transaction count for this merchant across active months only.
type: number
format: double
x-java-type: java.math.BigDecimal
average_monthly_amount:
description: Average monthly spend with this merchant across the full analysis window.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
average_monthly_amount_active:
description: Average monthly spend with this merchant across active months only.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
first_transaction_date:
description: Timestamp of the first transaction with this merchant.
type: string
format: date-time
last_transaction_date:
description: Timestamp of the most recent transaction with this merchant.
type: string
format: date-time
active_months:
description: Number of months with at least one transaction with this merchant.
type: integer
required:
- merchant_name
- transaction_count
- total_amount
- average_transaction_amount
- average_monthly_transactions
- average_monthly_transactions_active
- average_monthly_amount
- average_monthly_amount_active
- first_transaction_date
- last_transaction_date
- active_months
IncomeMonthlyTotal:
type: object
properties:
month:
description: The month of the reporting period
type: integer
format: int32
year:
description: The year of the reporting period
type: integer
format: int32
amount:
description: The total amount of transactions in the Month
type: number
count:
description: Number of transactions in the month
type: integer
format: int32
is_month_complete:
description: Indicates whether the data for this month is complete
type: boolean
x-class-extra-annotation: '@lombok.AllArgsConstructor'
x-toBuilder: true
CreditAssessmentBalance:
description: Balance statistics over the analysis period.
type: object
properties:
average_balance:
description: Average account balance over the analysis period.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
minimum_balance:
description: Minimum account balance observed during the analysis period.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
maximum_balance:
description: Maximum account balance observed during the analysis period.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
additionalProperties: false
required:
- average_balance
- minimum_balance
- maximum_balance
IncomeSourceType:
description: Classification of income source type (combined enum for all income sources)
type: string
enum:
- EMPLOYMENT
- RETIREMENT
- HOUSING_BENEFIT
- GIG_ECONOMY
- UNEMPLOYMENT
- RENTAL
- TRANSFER_FROM_OWN_APPLICATION
- STUDENT_STIPEND
- INVESTMENTS
- CITIZEN_ACCOUNT
- SOCIAL_SECURITY
- SIDE_BUSINESS
- BONUS
- CASH_DEPOSIT
BigPayments:
type: object
properties:
periods:
type: array
items:
$ref: '#/components/schemas/BigPaymentsPeriod'
required:
- periods
CreditObligationsV2Payload:
description: Insights payload wrapper carrying the lender-oriented credit-obligations
type: object
properties:
credit_obligations:
description: Lender-oriented credit obligations insights.
allOf:
- $ref: '#/components/schemas/CreditObligationsV2'
additionalProperties: false
required:
- credit_obligations
BehaviorsMerchantSection:
description: Merchant breakdown with detected-merchant count.
type: object
properties:
detected_merchant_count:
description: Number of distinct merchants detected.
type: integer
transaction_count:
description: Total number of classifiable debit transactions in the analysis window.
type: integer
breakdown:
description: One entry per detected merchant.
type: array
items:
$ref: '#/components/schemas/BehavioralMerchantBreakdown'
required:
- detected_merchant_count
- transaction_count
- breakdown
EmployerDetails:
type: object
properties:
name:
description: Official name of the employer in English and Arabic.
allOf:
- $ref: '#/components/schemas/Translation'
cr_number:
description: Employer’s Commercial Registration (CR) number.
type:
- integer
- 'null'
format: int64
CreditAssessmentRatioIndicator:
description: A ratio-based credit indicator including the computed rate, regulatory ceiling, and derived maximum installment.
type: object
properties:
rate:
description: The computed ratio as a decimal between 0 and 1.
type: number
ceiling:
description: The regulatory or policy ceiling for this ratio as a decimal between 0 and 1.
type: number
maximum_monthly_installment:
description: The maximum monthly installment the entity can afford based on this ratio and its ceiling.
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
additionalProperties: false
required:
- rate
- ceiling
- maximum_monthly_installment
FreelancerInflowsOutflows:
type: object
properties:
total_amount:
description: Total amount of inflows/outflows
allOf:
- $ref: '#/components/schemas/CurrencyAmount'
transactions_count:
description: Total number of transactions
type: integer
periods:
description: Historical data for different periods
type: array
items:
$ref: '#/components/schemas/FreelancerPeriodFactors'
CreditObligationsMonthlyTotal:
type: object
properties:
month:
description: The month number (1-12)
type: integer
format: int32
year:
description: The year
type: integer
format: int32
is_month_complete:
description: Indicates if the month has complete data
type: boolean
loan_repayments:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/AmountCount'
loan_received:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/AmountCount'
credit_cards_repayments:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/AmountCount'
credit_cards_spending:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/AmountCount'
credit_cards_balance:
type:
- object
- 'null'
allOf:
- $ref: '#/components/schemas/BalanceInsights'
ExpensesMonthlyAmount:
type: object
properties:
month:
description: 'Number of month within the year (e.g.: January is represented as 1 and December is represented as 12)'
type: integer
format: int32
year:
description: Year
type: integer
format: int32
amount:
description: Total expenses for the month
type: number
x-java-type: java.math.BigDecimal
required:
- amount
CreditObligationsOverall:
description
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lean-technologies/refs/heads/main/openapi/lean-technologies-behavioral-insights-new-api-openapi.yml