Get FI Balance

​

Overview

​

Use Cases

• PFM dashboard displays: Personal Finance Management applications that show users a consolidated view of all their account balances across different banks and financial institutions in a single interface.
• Account summary pages: Portfolio management and wealth tracking applications that display high-level net worth calculations based on current account balances.
• Quick balance checks: Mobile applications and widgets that provide users with at-a-glance balance information without the overhead of downloading complete transaction histories.
• Net worth tracking: Financial planning tools that monitor changes in total asset values over time by tracking balance snapshots at regular intervals.
• Multi-account aggregation: Services that consolidate balances from savings accounts, current accounts, fixed deposits, and recurring deposits to give users a complete picture of their liquid assets.

​

Authentication

​

HTTP Request

POST {{Base_URL}}/getfibalance

​

Request Parameters

​

Request Body Example

{
    "linkReferenceNumber": "e72534d6-0016-4f0e-9da5-3e05ad405394",
    "consentID": "3c92001e-57ea-4320-bbb8-66d524bfb435"
}

{
    "consentID": "3c92001e-57ea-4320-bbb8-66d524bfb435"
}

​

Response Format

​

Success Response

​

Response Parameters

​

Supported FI Types

​

Response Examples

{
    "ver": "1.21.0",
    "status": "success",
    "data": {
        "fiType": "DEPOSIT",
        "fipId": "finsharebank",
        "fipName": "FinShareBankServer",
        "balance": "101666.33",
        "linkReferenceNumber": "e72534d6-0016-4f0e-9da5-3e05ad405394",
        "maskedAccountNumber": "XXXXXXXX3900"
    }
}

{
    "ver": "1.21.0",
    "status": "success",
    "data": [
        {
            "fiType": "DEPOSIT",
            "fipId": "finsharebank",
            "fipName": "FinShareBankServer",
            "balance": "101666.33",
            "linkReferenceNumber": "e72534d6-0016-4f0e-9da5-3e05ad405394",
            "maskedAccountNumber": "XXXXXXXX3900"
        },
        {
            "fiType": "TERM_DEPOSIT",
            "fipId": "finsharebank",
            "fipName": "FinShareBankServer",
            "balance": "500000.00",
            "linkReferenceNumber": "a45678b9-1234-4567-89ab-cdef12345678",
            "maskedAccountNumber": "XXXXXXXX4567"
        },
        {
            "fiType": "RECURRING_DEPOSIT",
            "fipId": "anotherbank",
            "fipName": "AnotherBankServer",
            "balance": "75000.50",
            "linkReferenceNumber": "b56789c0-2345-5678-90bc-def123456789",
            "maskedAccountNumber": "XXXXXXXX7890"
        }
    ]
}

​

Error Handling

​

Error Response Format

​

Common Error Codes

​

Error Response Example

{
    "ver": "1.21.0",
    "timestamp": "2025-11-14T11:51:28.773Z",
    "errorCode": "InvalidConsentId",
    "errorMsg": "Consent ID does not exist.",
    "status": "failure"
}

​

Supported Account Types

• Current Account: Business or high-transaction-volume checking accounts, typically with no minimum balance requirements or transaction limits.
• Savings Account: Personal deposit accounts that earn interest on the balance, often with some transaction limits and minimum balance requirements.
• Fixed Deposit (Term Deposit): Time-bound deposits with fixed interest rates, where the balance represents the principal plus any accrued interest up to the query date.
• Recurring Deposit: Regular installment-based savings schemes where the balance shows the cumulative value of all deposits made plus any accrued interest.

​

Usage Notes and Best Practices

​

Retrieving Multiple Account Balances

• The most efficient way to retrieve balances for all accounts under a consent is to omit the linkReferenceNumber parameter entirely, which returns balance data for all linked accounts in a single API call.
• This bulk retrieval approach significantly reduces the number of API calls required for multi-account scenarios, improving application performance and reducing load on both client and server.
• When processing multiple accounts, iterate through the returned array and handle each account’s balance data independently, accounting for different FIP providers and account types.

​

Data Freshness and Balance Accuracy

• The balance returned represents the most recent data fetched from the Financial Information Provider, which may not be real-time depending on the FIP’s data provision schedule.
• For PERIODIC consents, balance data is refreshed according to the fetch frequency configured in your consent template (e.g., daily at midnight, weekly on Sundays).
• For ONETIME consents, the balance represents a snapshot at the time of initial data fetch and will not update automatically; users must initiate a new consent for updated information.
• Different banks and financial institutions have varying data update cycles; some provide near-real-time balance updates while others may have delays of several hours or update only once daily.

​

Balance Display and Formatting

• Balance values are returned as strings to preserve decimal precision; convert to numeric types carefully, using decimal or big number libraries to avoid floating-point precision errors.
• Always display currency symbols and formatting according to user locale preferences or the currency field if provided (typically INR for Indian accounts).
• Consider the account’s currency denomination when displaying balances, especially for forex accounts or international banking integrations.
• The masked account number provides just enough information for users to identify accounts while maintaining security; display this prominently alongside balance information.

​

Consent Lifecycle Management

• Always verify that a consent is in ACTIVE status before attempting to retrieve balance data, as paused, revoked, or expired consents will return errors.
• Monitor webhook notifications for consent lifecycle events (PAUSE, REVOKE, EXPIRE) and update your local consent status to prevent unnecessary API calls to inactive consents.
• Implement cache invalidation logic that clears cached balance data when consent status changes to inactive, preventing display of stale information.

​

Caching Strategy for Balance Data

• Balance information changes relatively infrequently compared to the rate at which users might query it, making caching an effective optimization strategy.
• Implement time-based cache expiration aligned with your consent’s fetch frequency (e.g., if data refreshes daily, cache balances for 23 hours).
• Consider implementing a “refresh” mechanism that allows users to explicitly trigger a new balance fetch when they need the latest information.
• Store the timestamp of the last balance fetch in your cache metadata to display data age to users, maintaining transparency about data freshness.

​

Rate Limiting and Performance Optimization

• This lightweight endpoint has lower computational overhead than transaction-fetching endpoints, but rate limits still apply to prevent abuse.
• Batch balance retrieval by using the multi-account capability (omitting linkReferenceNumber) rather than making individual API calls for each account.
• Implement client-side request throttling to spread API calls over time, especially during peak usage periods or when syncing data for many users simultaneously.
• Monitor the X-RateLimit-* headers in API responses to track your current usage against limits and adjust request patterns proactively.

​

Error Handling and Graceful Degradation

• When balance data is unavailable for any reason, consider displaying the last successfully retrieved balance with a clear indicator of staleness rather than showing no information.
• Implement retry logic with exponential backoff for transient failures, but respect terminal error states (invalid consent, authorization failures) to avoid wasted API calls.
• For multi-account balance requests, handle partial failures gracefully; if one account’s balance is unavailable, still display balances for accounts that succeeded.
• Log all error responses with full context (consent ID, link references, timestamp) to facilitate troubleshooting and identify systematic issues.

​

Integration with Transaction Data

• Use this endpoint for displaying quick balance summaries, then fetch detailed transaction history on-demand when users drill down into specific accounts.
• Cross-reference balance values from this endpoint with calculated balances from transaction history to detect discrepancies that might indicate data quality issues or missing transactions.
• Consider implementing a reconciliation process that compares the balance from this endpoint with the most recent transaction balance to validate data consistency.

​

Privacy and Security Considerations

• Balance information is sensitive financial data; ensure all storage, transmission, and display of this data complies with relevant data protection regulations (GDPR, DPDPA, etc.).
• Implement appropriate access controls to ensure users can only view balances for their own consents and accounts.
• Log access to balance data for audit trails, but sanitize logs to prevent exposure of actual balance values in production logging systems.
• When displaying balances in user interfaces, consider implementing additional authentication (biometric, PIN) for high-value account types.

​

Comparison with Other Data Endpoints

• Get FI Balance vs Get FI Data: Use Get FI Balance when you only need current balance information without transaction details, significantly reducing response payload size and processing overhead.
• Get FI Balance vs Get All FI Data: Get FI Balance is optimized for displaying balances across multiple accounts, while Get All FI Data provides comprehensive information including transactions, profiles, and summaries for in-depth analysis.
• When to use Get FI Balance: Dashboard displays, quick balance checks, net worth calculations, account summary pages, or any scenario where transaction-level detail is not immediately needed.
• When to use transaction endpoints: Spend analysis, transaction categorization, detailed account statements, reconciliation processes, or any feature requiring access to individual transaction records.

​

Related Endpoints

• Get FI Data: Retrieves comprehensive transaction history and account details for a specific account, including all transactions within the consent period.
• Get All FI Data: Fetches complete financial data including transactions, profiles, and summaries for all accounts linked to a consent.
• Get All Latest Data: Retrieves only incremental updates for PERIODIC consents, optimized for regular synchronization without redundant data transfer.
• Get FI Data XML: Provides account and transaction data in XML format for integrations requiring structured XML processing.