Skip to main content

Account Balances

The Account Balances API allows you to retrieve current and historical account balance information.
Attention

We are pleased to release Account Balances V2 (limited to BDAs only). You may access the documentation here.

Overview

The Account Balances API facilitates fetching current and historical bank account balances. Balances are the cash settled amount in a given account at the time of the API request.

The API provides additional details besides the balances within the return payload, enabling customized integration and reporting.

Getting started is as easy as sending an empty API request, which defaults to retrieving a list of current day balances for the cash reporting accounts configured with your API credentials.

View the Quick start section to learn how to initiate an API request.

Note
  • Depending on the account, the balance displayed in banking portals may or may not match the value returned by the API during intraday reporting.
  • When fetching balances of accounts, be aware the current day and prior day parameters will be processed according to the timezone the account is situated in. 
  • Balances returned in the balancesList will be sorted by asOfDate, in chronological order.

Use cases

  • Reporting
  • Cash flow forecasting
  • Amount-based event triggers
  • Liquidity
  • Sweep accounts
  • Customized reporting

Restrictions

  • All parameters are optional. However, when providing an accountList, the accountID and bankID fields are required in each account in the array.
  • When providing startDate and endDate, the date range cannot exceed 31 days.
  • Invalid parameter combinations:
    • startDate + relativeDateType
    • endDate + relativeDateType
    • startDate + endDate + relativeDateType

Note that the balance type returned is determined by the relativeDateType parameter submitted in the API call. Depending on this field, balances will either reflect the current day or priort day.

Automatic interpretation

  • When certain fields are not provided on the request, the API will calculate them.
  • When no parameters are provided, the API interprets the request to include the following:
    • relativeDateType=“CURRENT_DAY”
    • accountList includes all cash reporting accounts.
  • When startDate is provided without an endDate, the Access API interprets the endDate to be startDate + 31 days.
  • When endDate is provided without a startDate, the Access API interprets the startDate to be endDate - 31 days.

Success events

  • When a client provides a startDate or endDate on the Request,  the API returns the historical balances across the date range for your cash reporting accounts provided in the Request.
  • When providing relativeDateType of PRIOR_DAY, the API returns the prior day's balances for your cash reporting accounts provided in the Request.
  • When providing relativeDateType of CURRENT_DAY, the API returns the current day balances for your cash reporting accounts provided in the Request.
  • When providing a list of accountID, the system only returns the requested balances for the list of accounts.
  • Balances returned in the balancesList are sorted by asOfDate in chronological order.

Quick start

To quickly get started using the JPMorgan Account Balances API, follow the steps below.

Tip

In order to complete these steps, you will need bank accounts configured for cash reporting and API access with JPMorgan. Refer to your implementation manager to confirm that the configuration has been properly completed.

Procedure summary

  1. Set up API access
  2. Send default API request
  3. Receive synchronous response
  4. Send customized API request
  5. Receive synchronous response

1. Set up API access

When using the Account Balances API, you may use OAuth 2 or mutual TLS certificates.

OAuth

  • Upload CSR

TLS Certs

  • SSL Transport

2. Send default API request

To fetch Account Balances with the default request, form a request with empty fields, as shown in the example below.

Sending an empty request causes the API to use its default parameters (refer to Request field defaults).

Default request
Plaintext
Default Request

{}

When a default request is made without inclusion of account numbers, you will see balances for accounts to which you are entitled in the response. If however you do not have access to any accounts, the error code GCA-022 (no eligable accounts were found) is returned.

3. Receive synchronous response

Synchronous response
Plaintext
{
    "accountList": [
        {
            "accountId": "000000004045701",
            "accountName": "TEST ACCOUNT NAME",
            "branchId": "",
            "bankId": "02100002",
            "bankName": "JPMORGAN CHASE",
            "currency": {
                "code": "USD",
                "currencySequence": 0,
                "decimalLocation": 2,
                "description": "US DOLLAR"
            },
            "balanceList": [
                {
                    "asOfDate": "2021-12-08",
                    "recordTimestamp": "2022-07-08T05:44:20Z",
                    "currentDay": true,
                    "openingAvailableAmount": 0.00,
                    "openingLedgerAmount": 0.00,
                    "endingAvailableAmount": 0.00,
                    "endingLedgerAmount": 0.00
                }
            ]
        },
        {
            "accountId": "000000010013324",
            "accountName": "TEST ACCOUNT NAME",
            "branchId": "",
            "bankId": "02100002",
            "bankName": "JPMORGAN CHASE",
            "currency": {
                "code": "USD",
                "currencySequence": 0,
                "decimalLocation": 2,
                "description": "US DOLLAR"
            },
            "balanceList": [
                {
                    "asOfDate": "2021-12-08",
                    "recordTimestamp": "2022-07-08T05:18:38Z",
                    "currentDay": true,
                    "openingAvailableAmount": 33253003.18,
                    "openingLedgerAmount": 33253003.18,
                    "endingAvailableAmount": 33253003.18,
                    "endingLedgerAmount": 33253003.18
                }
            ]
        },
        {
            "accountId": "000000010900009",
            "accountName": "TEST ACCOUNT NAME",
            "branchId": "",
            "bankId": "02100002",
            "bankName": "JPMORGAN CHASE",
            "currency": {
                "code": "USD",
                "currencySequence": 0,
                "decimalLocation": 2,
                "description": "US DOLLAR"
            },
            "balanceList": [
                {
                    "asOfDate": "2021-12-08",
                    "recordTimestamp": "2022-07-08T05:18:38Z",
                    "currentDay": true,
                    "openingAvailableAmount": 0.00,
                    "openingLedgerAmount": 12223.50,
                    "endingAvailableAmount": 0.00,
                    "endingLedgerAmount": 12223.50
                }
            ]
        },
        {
            "accountId": "000000010957603",
            "accountName": "TEST ACCOUNT NAME",
            "branchId": "",
            "bankId": "02100002",
            "bankName": "JPMORGAN CHASE",
            "currency": {
                "code": "USD",
                "currencySequence": 0,
                "decimalLocation": 2,
                "description": "US DOLLAR"
            },
            "balanceList": [
                {
                    "asOfDate": "2021-12-08",
                    "recordTimestamp": "2022-07-08T05:18:38Z",
                    "currentDay": true,
                    "openingAvailableAmount": 140820110.41,
                    "openingLedgerAmount": 140820110.41,
                    "endingAvailableAmount": 140820110.41,
                    "endingLedgerAmount": 140820110.41
                }
            ]
        },
        {
            "accountId": "000000010962009",
            "accountName": "TEST ACCOUNT NAME",
            "branchId": "",
            "bankId": "02100002",
            "bankName": "JPMORGAN CHASE",
            "currency": {
                "code": "USD",
                "currencySequence": 0,
                "decimalLocation": 2,
                "description": "US DOLLAR"
            },
            "balanceList": [
                {
                    "asOfDate": "2021-12-08",
                    "recordTimestamp": "2022-07-08T05:20:10Z",
                    "currentDay": true,
                    "openingAvailableAmount": -4681826093.93,
                    "openingLedgerAmount": -4681786201.38,
                    "endingAvailableAmount": -4681826093.93,
                    "endingLedgerAmount": -4681786201.38
                }
            ]
        }
    ]
}

4. Send customized API request

You may customize your request with date and account list filters at the same time as shown below. This isn't necessary, but may help you refine your requests when needed. Refer to Constraints for filter combinations that are not allowed.

5. Receive synchronous response

Synchronous response
Plaintext
{
    "accountList": [
        {
            "accountId": "0041034035",
            "accountName": "TEST ACCOUNT NAME",
            "branchId": "",
            "bankId": "CHASGB2L",
            "bankName": "JPMORGAN CHASE",
            "currency": {
                "code": "GBP",
                "currencySequence": 0,
                "decimalLocation": 2,
                "description": "POUND STERLING"
            },
            "balanceList": [
                {
                    "asOfDate": "2022-06-29",
                    "recordTimestamp": "2022-08-03T20:43:00Z",
                    "currentDay": true,
                    "openingAvailableAmount": 642.76,
                    "openingLedgerAmount": 642.76,
                    "endingAvailableAmount": 642.76,
                    "endingLedgerAmount": 642.76
                },
                {
                    "asOfDate": "2022-06-28",
                    "recordTimestamp": "2022-08-03T20:43:00Z",
                    "currentDay": false,
                    "openingAvailableAmount": 1077.99,
                    "openingLedgerAmount": 1077.99,
                    "endingAvailableAmount": 642.76,
                    "endingLedgerAmount": 642.76
                }
            ]
        },
        {
            "accountId": "000000004045701",
            "accountName": "TEST ACCOUNT NAME",
            "branchId": "",
            "bankId": "02100002",
            "bankName": "JPMORGAN CHASE",
            "currency": {
                "code": "USD",
                "currencySequence": 0,
                "decimalLocation": 2,

Request filters

Request filters:
Request Field Defined API Response
startDate, endDate Historical balances across the date range for cash reporting accounts
relativeDateType = PRIOR_DAY Prior day balances for cash reporting accounts
relativeDateType = CURRENT_DAY Current day balances for cash reporting accounts
accountList Only the requested balances for the provided list of accounts.

Request examples

Query by Date Range for a single specified account

Date range request
Json
{
  "startDate": "2018-01-01",
  "endDate": "2018-01-05",
  "accountList": [
    {
      "accountId": "00000000000000304266256"
    }
  ]
}

Query by Date Range for multiple specified accounts

JSON
Json
{
  "startDate": "2018-01-01",
  "endDate": "2018-01-05",
  "accountList": [
    {
      "accountId": "00000000000000304266256,00000000000000010962009"
    }
  ]
}

Of note: When submitting multiple accounts, valid accounts will return data, while invalid accounts will return the error code GCA-010 (the account was not found). If all submitted accounts are invalid, the error GCA-009 is returned (the requested accounts were not found).

Query by Relative Date Type: Current Day

JSON
Json
{
  "relativeDateType": "CURRENT_DAY",
  "accountList": [
    {
      "accountId": "00000000000000304266256"
    }
  ]
}

Query by Relative Date Type: Prior Day

JSON
Json
{
  "relativeDateType": "PRIOR_DAY",
  "accountList": [
    {
      "accountId": "00000000000000304266256"
    }
  ]
}

Request field defaults

When certain fields are not provided in the request, the API will default/calculate them.

When no parameters for the below fields are provided, the API interprets the request to include:

Field defaults:
Empty field name Default value
relativeDateType “CURRENT_DAY”
accountList all cash reporting accounts
endDate startDate + 31 days
startDate endDate - 31 days

Ledger states

When you receive a response to an Account Balances API request, you will see balance amounts described with four different amount parameters:

  • openingAvailableAmount
  • openingLedgerAmount
  • endingAvailableAmount
  • endingLedgerAmount
Example ledger states
Json
"balanceList": [
        {
          "asOfDate": "2020-03-05",
          "recordTimestamp": "2020-06-03T14:07:11Z",
          "currentDay": true,
          "openingAvailableAmount": 9217.81,
          "openingLedgerAmount": 9217.81,
          "endingAvailableAmount": 9217.81,
          "endingLedgerAmount": 9217.81
        }
      ]

These amounts may be the same, or they may differ depending on the state of pending transactions during the date in question.

Example ledger states 2
Json
"balanceList": [
        {
          "asOfDate": "2020-03-05",
          "recordTimestamp": "2020-06-03T14:07:11Z",
          "currentDay": true,
          "openingAvailableAmount": 110.9,
          "openingLedgerAmount": 822.86,
          "endingAvailableAmount": 243.05,
          "endingLedgerAmount": 640.52
        }
      ]

Ledger states defined

Ledger state descriptions:
Response amount Definition
openingAvailableAmount Amount available to withdraw from the account at the beginning of the provided date.
openingLedgerAmount Amount (including pending transactions) to settle in the account at the beginning of the provided date.
endingAvailableAmount Amount available to withdraw from the account at the end of the provided date.
endingLedgerAmount Amount (including pending transactions) to settle in the account at the end of the provided date.

Constraints

This section covers limits when using the Account Balances API.

Be aware of the below constraints when sending requests, or you may receive errors.

  • When providing startDate and endDate, the date range cannot exceed 31 days.
  • You may fetch balances for up to 200 accounts at a time.
  • Invalid parameter combinations:
    • startDate + relativeDateType
    • endDate + relativeDateType
    • startDate + endDate + relativeDateType

There are mutually exclusive filter combinations to use when sending a request; refer to Request filters for the list of possible filters.

Support

This section covers how to get support for the Account Balances API.

Urgent issues

Call the dedicated Payments/API Support team anytime at +1-978-805-1200 (Option 6).

Provide following details when calling support

  • Your name
  • Company ID
  • Any error messages being encountered

Non-urgent issues

Please email api.service.support@jpmchase.com.

Provide following details when emailing support:

  • Your name
  • Company ID
  • Any error messages being encountered
    • API product: [Insert API product name (i.e. RTP, Account Balance)]
    • API URL: [Choose one of the below two (2) current options]
      • Date the API call was made: [Insert date]
      • Time the API call was made: [Insert time and time zone]
    • Client identifier: [Insert Domain Name if using SSL certificates]
    • Description of the errors you are experiencing: [Insert error code or logs/error information you are seeing]

Next Steps

Getting Started

Complete the onboarding process to ensure you have everything you need.

Authentication

Learn how J.P. Morgan protects your transactions.