Finpass API Collection
  1. AA-BSA Analyzer
  • Introduction
  • Bank Statement Analyser
    • Upload Statement
      POST
    • Statement Result
      GET
  • Account Aggregator
    • Initialize
      POST
    • Fetch JSON Report
      POST
    • Fetch PDF Report
      POST
    • Refresh Data
      POST
  • Multi Bureau
    • Multi-Bureau Fetch
      POST
  • Corporate
    • CIN Lookup
      POST
    • LLPIN
      POST
    • PAN Lookup
      POST
    • Company Autocomplete
      POST
  • EPFO
    • EPFO-CRIF Combined Report
      POST
  • ITR Analyzer
    • Initialize
      POST
    • Status
      GET
    • ITR Analyzer — Get Full Data
      GET
  • AA-BSA Analyzer
    • Initialize
      POST
    • Status
      GET
    • AA BSA — Statement Result
      GET
    • AA BSA — Analysis JSON
      GET
  1. AA-BSA Analyzer

AA BSA — Analysis JSON

GET
/api/v1/aa-bsa-journey/analysis-json

AA BSA — Analysis JSON#

Endpoint Overview
GET /api/v1/aa-bsa-journey/analysis-json?client_id=<client_id>

Description#

The AA BSA Analysis JSON API returns structured, underwriting-ready Bank Statement Analysis (BSA) insights derived from the fetched transaction data. Rather than requiring manual analysis of raw transactions, this endpoint delivers pre-computed financial signals — covering income assessment, fixed obligations, monthly cash flow trends, and risk flags — in a single, clean JSON response.
This is the primary data input for automated credit decisioning and is available only after the journey status reaches analysis_complete.
Key Benefits
Skip manual statement analysis — get underwriting-ready signals in milliseconds
Assess income stability, FOIR, and monthly balance trends without building your own parser
Detect risk flags such as EMI bounces, salary reversals, and end-of-month stress automatically
Use income_stability_score and fixed_obligations_ratio as direct inputs into your credit scorecard

Use Cases#

Banking & Lending
Fintech & Payments
Enterprise & Compliance
Use average_monthly_income and income_stability_score to validate declared salary during loan underwriting
Apply fixed_obligations_ratio (FOIR) directly to check eligibility against RBI-prescribed limits
Trigger automated loan approval or rejection workflows based on flag values

Technical Implementation#

1
Authentication
All API requests require authentication using your Finpass API credentials passed as request headers.
1.
Obtain API Credentials: Register with Finpass to receive your X-API-KEY and X-API-SECRET.
2.
Include in Requests: Add both keys to every request as HTTP headers.
HeaderValue
X-API-KEYYour assigned API Key
X-API-SECRETYour assigned API Secret
Base URL: https://api.finpass.ai
2
Request Parameters

Request Headers#

HeaderRequiredDescription
X-API-KEYYesYour Finpass API Key
X-API-SECRETYesYour Finpass API Secret

Query Parameters#

ParameterTypeRequiredDescription
client_idstringYesThe client_id received from the /aa-bsa-journey/init response

Example Request#

GET /aa-bsa-journey/analysis-json?client_id=bsa_clnt_a1b2c3d4e5f6
3
Process Response

Response Parameters#

Top-Level#

ParameterTypeDescription
successbooleanIndicates whether the request was processed successfully
messagestringHuman-readable status message
data.client_idstringThe session identifier
data.analysis_periodobjectStart and end dates of the statement period analysed

data.summary — Financial Summary#

ParameterTypeDescription
total_creditsnumberTotal money credited across all accounts in the period (in INR)
total_debitsnumberTotal money debited across all accounts in the period (in INR)
average_monthly_balancenumberAverage end-of-month balance across all accounts (in INR)
minimum_monthly_balancenumberLowest month-end balance recorded in the analysis period (in INR)

data.income — Income Assessment#

ParameterTypeDescription
average_monthly_incomenumberAverage net monthly income inferred from detected salary credits (in INR)
income_stability_scorenumberScore from 0–100 indicating regularity and consistency of income; higher is better
identified_salary_creditsarrayMonth-wise breakdown of detected salary credits with source and amount
identified_salary_credits[].monthstringMonth of the credit (YYYY-MM)
identified_salary_credits[].amountnumberSalary credit amount for that month (in INR)
identified_salary_credits[].sourcestringEmployer or source name identified from the transaction narration

data.obligations — Fixed Obligations#

ParameterTypeDescription
total_emi_per_monthnumberTotal fixed EMI/loan repayments detected per month (in INR)
fixed_obligations_rationumberFOIR — ratio of fixed monthly obligations to average monthly income (e.g., 0.326 = 32.6%)
emi_accountsarrayList of individual EMI debits identified in the transaction history
emi_accounts[].lenderstringLender name inferred from the transaction narration
emi_accounts[].amountnumberMonthly EMI amount (in INR)
emi_accounts[].modestringPayment mode used for the EMI (e.g., NACH, IMPS)

data.cash_flow — Monthly Cash Flow#

ParameterTypeDescription
monthly_trendarrayMonth-wise breakdown of total credits, debits, and net cash flow
monthly_trend[].monthstringMonth (YYYY-MM)
monthly_trend[].total_creditsnumberTotal credits in that month (in INR)
monthly_trend[].total_debitsnumberTotal debits in that month (in INR)
monthly_trend[].netnumberNet cash flow for the month — credits minus debits (in INR)

data.flags — Risk Signals#

FlagTypeDescription
salary_bouncebooleantrue if any salary credit was reversed or returned in the period
emi_bouncebooleantrue if any EMI debit failed or was returned
high_cash_withdrawalbooleantrue if unusually large or frequent ATM cash withdrawals were detected
inward_cheque_returnbooleantrue if any inward cheques were returned unpaid
end_of_month_stressbooleantrue if the account balance drops critically low at month-end on a recurring basis

Example Successful Response#

{
  "success": true,
  "message": "BSA analysis fetched successfully",
  "data": {
    "client_id": "bsa_clnt_a1b2c3d4e5f6",
    "analysis_period": {
      "from": "2023-11-01",
      "to": "2024-10-31"
    },
    "summary": {
      "total_credits": 1125000.00,
      "total_debits": 987340.50,
      "average_monthly_balance": 32450.75,
      "minimum_monthly_balance": 7400.50
    },
    "income": {
      "average_monthly_income": 85000.00,
      "income_stability_score": 91,
      "identified_salary_credits": [
        { "month": "2024-10", "amount": 85000.00, "source": "INFOSYS LIMITED" },
        { "month": "2024-09", "amount": 85000.00, "source": "INFOSYS LIMITED" },
        { "month": "2024-08", "amount": 85000.00, "source": "INFOSYS LIMITED" },
        { "month": "2024-07", "amount": 82000.00, "source": "INFOSYS LIMITED" },
        { "month": "2024-06", "amount": 82000.00, "source": "INFOSYS LIMITED" },
        { "month": "2024-05", "amount": 82000.00, "source": "INFOSYS LIMITED" }
      ]
    },
    "obligations": {
      "total_emi_per_month": 27700.00,
      "fixed_obligations_ratio": 0.326,
      "emi_accounts": [
        { "lender": "HDFC HOME LOAN", "amount": 18500.00, "mode": "NACH" },
        { "lender": "BAJAJ FINANCE", "amount": 9200.00, "mode": "IMPS" }
      ]
    },
    "cash_flow": {
      "monthly_trend": [
        { "month": "2024-10", "total_credits": 90200.00, "total_debits": 78340.00, "net": 11860.00 },
        { "month": "2024-09", "total_credits": 88500.00, "total_debits": 81200.00, "net": 7300.00 },
        { "month": "2024-08", "total_credits": 91000.00, "total_debits": 76500.00, "net": 14500.00 },
        { "month": "2024-07", "total_credits": 86400.00, "total_debits": 80100.00, "net": 6300.00 },
        { "month": "2024-06", "total_credits": 85200.00, "total_debits": 79800.00, "net": 5400.00 },
        { "month": "2024-05", "total_credits": 87000.00, "total_debits": 78200.00, "net": 8800.00 }
      ]
    },
    "flags": {
      "salary_bounce": false,
      "emi_bounce": false,
      "high_cash_withdrawal": false,
      "inward_cheque_return": false,
      "end_of_month_stress": false
    }
  }
}

Possible Error Responses#

Journey Not Complete
Invalid Client ID
Unauthorized
{
  "success": false,
  "message": "Analysis is not yet available. Journey status is 'data_fetched'. Please poll /status until status is 'analysis_complete'.",
  "error_code": "JOURNEY_INCOMPLETE"
}
Returned when this endpoint is called before the journey reaches analysis_complete.

Integration Best Practices#

Security Recommendations
Call this endpoint exclusively from your secure backend — analysis data must never be returned raw to a frontend client
Apply role-based access controls so only credit underwriters or automated systems can consume analysis output
Log all analysis fetches with the client_id, timestamp, and requesting user for compliance audit trails
Do not cache analysis results beyond the loan application lifecycle — purge data once decisioning is complete
User Experience Guidelines
Always verify journey status via /status before calling this endpoint to avoid JOURNEY_INCOMPLETE errors
Use income_stability_score as a quick confidence signal — scores above 75 generally indicate stable salaried income
Surface flags as soft decline reasons and offer manual review options when one or more flags are true
Display fixed_obligations_ratio as a percentage (e.g., 0.326 → 32.6% FOIR) in your underwriting dashboard for readability

Code Samples#

cURL
Python
Node.js
Related APIs
AA BSA — Init Journey — Start a new AA BSA journey session and receive the consent link
AA BSA — Poll Status — Check the current state of an ongoing AA BSA journey session
AA BSA — Statement Result — Retrieve the raw bank account and transaction data for this session
Compliance and Legal Considerations
BSA analysis data is derived from financial information collected under explicit user consent via the RBI Account Aggregator framework. This data must only be used for the purpose declared at the time of consent (loan_underwriting or loan_monitoring) and must not be repurposed, sold, or shared with unauthorised third parties. Automated credit decisions made using this data must comply with the RBI Fair Practices Code and applicable consumer protection regulations. Retain analysis records only for the duration mandated by your regulatory framework and implement appropriate data deletion policies thereafter. Access to this endpoint requires the AA_BSA_JOURNEY permission on your Finpass account.

Request

Query Params

Responses

🟢200Success
application/json
Body

Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request GET 'https://api.finpass.ai/api/v1/aa-bsa-journey/analysis-json?client_id=<client_id>'
Response Response Example
{
  "success": true,
  "status_code": 200,
  "message": "Journey analysis retrieved successfully",
  "data": {
    "client_id": "aabsa_69c0e33a_ecf10acbff2e1d7583f1ff39",
    "status": "completed",
    "total_accounts": 2,
    "accounts": [
      {
        "account_index": 0,
        "bank_name": "FDRLFIPPROD",
        "account_number": "XXXXXXXXXX8687",
        "bsa_status": "completed",
        "bsa_client_id": "bank_statement_42c3805ba50c",
        "analysis_json": {
          "entity_type": "individual",
          "health_score": {
            "score": 100,
            "rating": "Excellent",
            "rating_description": "Statement shows strong financial health with minimal risk indicators.",
            "total_penalties": 0,
            "breakdown": {
              "bounces": {
                "count": 0,
                "penalty": 0
              },
              "negative_balances": {
                "count": 0,
                "penalty": 0
              },
              "reconciliation_issues": {
                "count": 0,
                "penalty": 0
              }
            },
            "details": {
              "breakdown": {
                "bounces": {
                  "count": 0,
                  "weight": 1,
                  "penalty": 0
                },
                "negative_balances": {
                  "count": 0,
                  "weight": 1,
                  "penalty": 0
                },
                "reconciliation_issues": {
                  "count": 0,
                  "weight": 1,
                  "penalty": 0
                }
              },
              "thresholds": {
                "excellent": ">= 90",
                "good": ">= 75",
                "fair": ">= 50",
                "poor": ">= 25",
                "critical": "< 25"
              }
            }
          },
          "flagged_transactions": {
            "bounce_transactions": [],
            "negative_balance_transactions": [],
            "reconciliation_issues": [],
            "date_mismatch_transactions": [],
            "cheque_return_summary": {},
            "summary": {
              "total_flagged": 0,
              "bounce_count": 0,
              "negative_balance_count": 0,
              "reconciliation_count": 0,
              "date_mismatch_count": 0
            }
          },
          "suspicious_transactions": {
            "suspicious_credits": [],
            "suspicious_debits": [],
            "monthwise_summary": {},
            "summary": {
              "total_suspicious": 0,
              "suspicious_credit_count": 0,
              "suspicious_debit_count": 0
            }
          },
          "summary_card": {
            "customer_name": "RAJESH KUMAR",
            "account_number": "XXXXXXXXXX2121",
            "bank_name": "federal",
            "ifsc_code": "FDRL001121",
            "account_type": "Savings",
            "statement_period": {
              "start_date": "05-08-2025",
              "end_date": "22-03-2026",
              "days": 230,
              "months": 8
            },
            "balance_summary": {
              "opening_balance": 0,
              "closing_balance": 1042.27,
              "average_balance": 14237.26,
              "max_balance": 98780.65,
              "min_balance": 0
            },
            "transaction_summary": {
              "total_transactions": 237,
              "total_credits": 797488,
              "total_debits": 796445.73,
              "credit_count": 34,
              "debit_count": 202,
              "net_flow": 1042.27
            },
            "mode_breakdown": {
              "debit": {
                "count": 12,
                "total_credit": 0,
                "total_debit": 13720.51
              },
              "credit_neft": {
                "count": 8,
                "total_credit": 763658,
                "total_debit": 0
              },
              "debit_upi": {
                "count": 169,
                "total_credit": 0,
                "total_debit": 602120.5
              },
              "debit_imps": {
                "count": 6,
                "total_credit": 0,
                "total_debit": 135022
              },
              "credit_upi": {
                "count": 9,
                "total_credit": 7428,
                "total_debit": 0
              },
              "debit_wallet": {
                "count": 2,
                "total_credit": 0,
                "total_debit": 790
              },
              "debit_upi_p2m": {
                "count": 2,
                "total_credit": 0,
                "total_debit": 280
              },
              "credit": {
                "count": 2,
                "total_credit": 37,
                "total_debit": 0
              },
              "debit_upi_p2m_shopping": {
                "count": 1,
                "total_credit": 0,
                "total_debit": 554
              },
Previous
AA BSA — Statement Result
Built with