> ## Documentation Index > Fetch the complete documentation index at: https://docs2.finverse.com/llms.txt > Use this file to discover all available pages before exploring further. # Get balance history > Retrieve Balance History information for a specific Account (using a specific `account_id`). **Authorization**: `login_identity_token` ## Request parameters (optional) Use the following optional URL parameters to customize the source of balance history records. (e.g. `GET /balance_history/{account_id}?source=COMPUTED`) Notes: - `source=INSTITUTION`: Default behaviour. Returns Balance history as reported by the institution. Available for all institutions where Balance History product is supported. - `source=COMPUTED`: Alternative behaviour. Returns balance history by computing based on the transactions for that specific account. Available for all institutions where Transactions product is supported. ### accounts Full Account object for the specified `account_id`. See `GET /accounts` for details. ### balance_history (array) Full `balance_history` array, containing a history of end-of-day account balances on specified dates. Balances are returned in reverse-chronological order (i.e. most recent balance first). ### institution Summary Institution object. See `GET /institutions` for details. ### login_identity Summary Login Identity object. See `GET /login_identity` for details. ## OpenAPI ````yaml /api-reference/openapi.json get /balance_history/{accountId} openapi: 3.0.0 info: description: Documentation of the early finverse services title: Finverse Public termsOfService: https://example.com contact: name: Maintainers email: info@finverse.com license: name: unknown license version: 0.0.1 servers: - url: https://api.prod.finverse.net security: - Oauth2: - test tags: - name: public description: Publicly accessible endpoints x-group: Public - name: customer description: Customer app and institution endpoints x-group: Customer - name: link description: Finverse Link flows x-group: Link - name: login_identity description: Login identity lifecycle and metadata x-group: Login identity - name: accounts description: Accounts, balances, and account numbers x-group: Accounts - name: statements description: Statements and composite statements x-group: Statements - name: transactions description: Transaction history x-group: Transactions - name: identity_income description: Identity and income insights x-group: Identity & income - name: payment_links description: Payment link creation and checkout x-group: Payment links - name: mandates description: Direct debit mandates x-group: Mandates - name: payments description: Payment initiation and status x-group: Payment operations - name: payouts description: Payouts and scheduled payouts x-group: Payouts - name: payment_users description: Payment user profiles x-group: Payment users - name: payment_accounts description: Payment accounts for users x-group: Payment accounts - name: payment_methods description: Stored payment methods x-group: Payment methods - name: bills description: Bill presentment x-group: Bills - name: disputes description: Payment disputes x-group: Disputes - name: ledger description: Ledger and statements x-group: Ledger paths: /balance_history/{accountId}: get: tags: - accounts summary: Get balance history description: >- Retrieve Balance History information for a specific Account (using a specific `account_id`). **Authorization**: `login_identity_token` ## Request parameters (optional) Use the following optional URL parameters to customize the source of balance history records. (e.g. `GET /balance_history/{account_id}?source=COMPUTED`) Notes: - `source=INSTITUTION`: Default behaviour. Returns Balance history as reported by the institution. Available for all institutions where Balance History product is supported. - `source=COMPUTED`: Alternative behaviour. Returns balance history by computing based on the transactions for that specific account. Available for all institutions where Transactions product is supported. ### accounts Full Account object for the specified `account_id`. See `GET /accounts` for details. ### balance_history (array) Full `balance_history` array, containing a history of end-of-day account balances on specified dates. Balances are returned in reverse-chronological order (i.e. most recent balance first). ### institution Summary Institution object. See `GET /institutions` for details. ### login_identity Summary Login Identity object. See `GET /login_identity` for details. operationId: getBalanceHistory parameters: - description: The account id name: accountId in: path required: true schema: type: string - description: >- The source will determine what type of balance history will be returned name: source in: query schema: type: string enum: - INSTITUTION - COMPUTED responses: '200': description: Successful content: application/json: schema: $ref: '#/components/schemas/GetBalanceHistoryResponse' examples: success: summary: Success value: account: account_currency: HKD account_id: 01GX8089798E6QP42V164FFQJG account_name: HKD Statement Savings account_number_masked: 111XXXXX6666 account_type: subtype: SAVINGS type: DEPOSIT balance: currency: HKD raw: '3333.33' value: 3333.33 created_at: '2023-04-05T06:04:21.000Z' group_id: 01GX80897FBK8S67SBWYZQEE97 is_closed: false is_excluded: false is_parent: false statement_balance: currency: HKD raw: '3333.33' value: 3333.33 updated_at: '2023-04-05T06:04:21.000Z' balance_history: - amount: 3333.33 currency: HKD date: '2020-11-22' - amount: 2913.33 currency: HKD date: '2020-11-12' - amount: 3013.33 currency: HKD date: '2020-11-01' - amount: 19806.58 currency: HKD date: '2020-09-18' - amount: 19806.58 currency: HKD date: '2020-09-10' - amount: 3083.02 currency: HKD date: '2020-09-08' - amount: 19791.03 currency: HKD date: '2020-08-24' - amount: 19791.02 currency: HKD date: '2020-08-17' institution: countries: - HKG - IDN - MYS - PHL - SGP - THA - VNM institution_id: testbank institution_name: Testbank (HK) portal_name: Testbank Online Banking login_identity: last_session_id: 01GX8083VWHVK7SREZ3JRZQYMV login_identity_id: 01GX8083SFS7DSJT8K0XKGDPH9 status: DATA_RETRIEVAL_COMPLETE source: INSTITUTION '400': description: Invalid Request content: application/json: schema: $ref: '#/components/schemas/BadRequestModelV2' examples: no_balance_history_found_for_account_id: summary: Error (no balance history found for account_id) value: error: code: 40101 message: The given accountId does have balance history available name: BALANCE_HISTORY_UNAVAILABLE product_not_supported: summary: Error (product not supported) value: error: code: 40012 details: Balance history is not supported for this bank error_code: PRODUCT_NOT_SUPPORTED message: >- Requested product is not yet supported for this institution. Please refer to Institutions list for details on products supported. request_id: '{unique_id}' type: API_ERROR account_not_found: summary: Error (Account not found) value: error: code: 40004 error_code: ACCOUNT_NOT_FOUND message: >- account_id cannot be found. Resource does not exist, has been deleted, or is no longer accessible. request_id: '{unique_id}' type: API_ERROR '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/BadRequestModelV2' security: - Oauth2: - balance_history components: schemas: GetBalanceHistoryResponse: properties: account: $ref: '#/components/schemas/Account' balance_history: type: array items: $ref: '#/components/schemas/BalanceHistory' institution: $ref: '#/components/schemas/InstitutionShort' login_identity: $ref: '#/components/schemas/LoginIdentityShort' source: type: string enum: - INSTITUTION - COMPUTED BadRequestModelV2: properties: error: type: object required: - type - code - error_code - message - request_id properties: code: type: integer example: 40004 details: type: string error_code: type: string example: CREDENTIALS_INVALID message: type: string request_id: description: The request_id provided in the request header type: string type: description: The error type type: string enum: - LINK_ERROR - API_ERROR example: LINKING_ERROR Account: required: - is_parent - is_closed - is_excluded - account_id - account_name - group_id - metadata properties: account_currency: type: string example: HKD description: >- Currency of the account (e.g. USD). Usually available, but may be null for zero-balance accounts (e.g. multi-currency or time-deposit account with zero balance). account_holder_name: type: string example: John Doe description: >- (Deprecated) Account holder name (if provided by the institution). Replaced by GET /identity. account_id: type: string example: 01ARZ3NDEKTSV4RRFFQ69G5FAV description: >- Finverse account ID. This is deterministically computed, such that the same account record provided by an institution across 2 or more data retrieval sessions will always have the same `account_id`. account_name: type: string example: HKD Savings description: End-user recognizable name for the account. account_nickname: type: string example: Emergency Fund description: >- Nickname for the account (if provided by the instiution). This is typically a custom account name set by the end-user. account_number_masked: type: string example: 123XXXXXX89 description: >- Masked account number. Format: preserves original length; shows first 0-4 digits + last 2-4 digits in plain text (depending on original length); omits spaces/symbols. account_sub_type: type: string example: TIME_DEPOSIT account_type: $ref: '#/components/schemas/AccountType' description: '**Beta**: account type object' balance: $ref: '#/components/schemas/CurrencyAmount' description: Balance object, in the account_currency country: type: string example: HKG description: 3-letter country code for the account (e.g. "HKG") created_at: type: string format: date-time description: >- Timestamp for when the account's record was first written to Finverse's database. group_id: description: >- ID used to identify a group of related parent + sub-accounts. This is deterministically computed based on the shared account number of the related accounts. type: string example: 03504faef9ad3ac048c6a43efa6db7ba1c5239a856536839d87ac949559e7ceb is_closed: type: boolean example: false description: Reserved for future use. is_excluded: type: boolean example: false description: Reserved for future use. is_parent: type: boolean example: false description: >- Flag for parent/master accounts (e.g. "Integrated Account" in Hong Kong). To avoid showing duplicate accounts, we recommend disregarding parent account data and referring instead to associated sub-accounts (using `group_id`). ledger_balance: $ref: '#/components/schemas/CurrencyAmount' metadata: type: object additionalProperties: type: string description: >- **Beta**: Metadata object, containing additional account information (for some institutions only) statement_balance: $ref: '#/components/schemas/CurrencyAmount' description: >- Balance object, in the institution's reporting or statement currency (if provided by the institution). E.g. balance in HKD for a USD Savings account at a Hong Kong bank. If not provided by the institution, the `statement_balance` will be same as `balance`. updated_at: type: string format: date-time description: Timestamp of the last update to the account's record. BalanceHistory: required: - date - amount - currency properties: amount: $ref: '#/components/schemas/FvDecimal' description: >- Balance amount (as of the end of day on the specified `date`). Sign follows financial statement conventions (positive sign: money received / income; negative sign: money sent / expenses). currency: description: Currency of the balance `amount` type: string example: HKD date: description: Date of the balance `amount` type: string example: '2021-10-27' InstitutionShort: properties: countries: type: array items: type: string example: - HKG institution_id: type: string example: 123 institution_name: type: string example: Mock Bank portal_name: type: string example: Personal Internet Banking LoginIdentityShort: properties: last_session_id: type: string format: ulid login_identity_id: type: string format: ulid status: type: string example: LINKING AccountType: properties: subtype: type: string enum: - CURRENT - SAVINGS - TIME_DEPOSIT - OTHER - CREDIT_CARD - DEBIT_CARD - SECURITIES - FUNDS - STOCKS - BONDS - MORTGAGE - PERSONAL_LOAN - REVOLVING_LOAN - UNKNOWN example: SAVINGS description: >- Secondary classification of the account. Possible values: `BONDS`, `CURRENT`, `CREDIT_CARD`, `DEBIT_CARD`, `FUNDS`, `MORTGAGE`, `PERSONAL_LOAN`, `RETIREMENT`,`REVOLVING_LOAN`, `SAVINGS`, `SECURITIES`, `STOCKS`, `TIME_DEPOSIT`, `OTHER`, `UNKNOWN` type: type: string enum: - DEPOSIT - CARD - INVESTMENT - LOAN - UNKNOWN example: DEPOSIT description: >- Primary classification of the account. Possible values: `CARD`, `DEPOSIT`, `INVESTMENT`, `LOAN`, `OTHER`, `UNKNOWN` CurrencyAmount: required: - value properties: currency: type: string example: HKD description: >- Currency of the `value`. Usually available, but may be null if value is 0 raw: type: string example: '69.00' description: >- Raw amount (as reported by the institution). Usually available, but may be null if value is 0. Intended for QA only value: $ref: '#/components/schemas/FvDecimal' description: >- Amount. Sign follows financial statement conventions (positive sign: assets / money in; negative sign: liabilities / money out) FvDecimal: type: number x-go-type: embedded: true import: package: gitlab.com/finverse/gitops/applications/common-go/amount type: FvDecimal securitySchemes: Oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://finverse-dev.us.auth0.com/oauth/token scopes: account: Account balance: Balance credit: Credit institution: Institution investment: Investment link: Link test: Test transaction: Transaction ````