> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fetch Real Time Balance Data
**LEGACY GUIDE**
This guide is for Platform API v2011101. For guidance on the newest version, see [Connectivity Integration Guides](/products/connectivity/overview/connectivity-integration-guides/).
The Platform API's balance check feature enables you to get real-time account balance information. This means the up-to-date balance information as it would appear on digital banking website, for instance. This can be critical to the success of any number of use cases including payments and account origination. Balance checks differ from standard aggregation because no transaction data is gathered, only account information.
This guide will take you through the balance check process using API endpoints. After reading this guide, you'll be able to:
* Gather balance information.
* Read balance information.
## API Workflow
**INFO**
For most use cases, balance checks are performed for already existing users and members as part of a larger process such as moving money or originating a new held account. To avoid confusion and unnecessary work, the steps in this guide assume these already exist. If your test or use case requires it, you may need to first create a user and a member.
The workflow for performing a balance check is as follows:
1. Start the balance check process.
2. Poll the member's connection status.
3. Answer multifactor authentication, if necessary.
4. Poll the member's connection status again until it reaches an end state.
* A successful end state is when the connection\_status is CONNECTED and the is\_aggregating field changes from true to false.
5. List the member's account information or read a particular account's information.
## 1. Call the Check Balance Endpoint
To make this request, you'll need an existing `user_guid` and `member_guid` as stated above.
Make a POST request to `/users/{user_guid}/members/{member_guid}/check_balance`. This request only starts the balance aggregation process; actually reading the aggregated data comes later. The response will be a `member` object with information about the state of the balance check process that just started.
```shell theme={null}
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/check_balance' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json'
```
```json theme={null}
{
"member": {
"aggregated_at": null,
"background_aggregation_is_disabled": false,
"connection_status": "CREATED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": true,
"is_managed_by_user": true,
"is_manual": false,
"is_oauth": false,
"metadata": null,
"most_recent_job_detail_code": 1000,
"most_recent_job_detail_text": "",
"name": "MX Bank",
"oauth_window_uri": null,
"successfully_aggregated_at": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": null
}
}
```
## 2. Check the Connection Status
Check the connection status of the member to get information on the state of the balance aggregation. Important fields include `connection_status`, `is_being_aggregated`, and `successfully_aggregated_at`. The `is_being_aggregated` field will tell you whether the balance aggregation is ongoing or complete.
When you see `"connection_status": "CONNECTED"` and `"is_being_aggregated": false` at the same time, the balance aggregation is done and you can move on to the next step.
You may need to check the connection status several times until an end state is reached.
Make a request to the [Read Member Status endpoint](/api-reference/platform-api/reference/read-member-status) (`GET /users/{user_guid}/members/{member_guid}/status`). The response in the example shows a successful end state.
```shell theme={null}
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"member": {
"aggregated_at": "2020-05-07T22:01:00Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"is_authenticated": true,
"is_being_aggregated": false,
"successfully_aggregated_at": "2020-05-07T22:01:25Z"
}
}
```
## 3. Deal with Multifactor Authentication
Aggregation-type jobs such as balance checks may trigger multifactor authentication (MFA) from the institution associated with the member. This is indicated by `connection_status: CHALLENGED`.
Please see the detailed section on [answering MFA challenges](/products/connectivity/overview/mfa) for more information. For this part of the guide, we'll assume there was no MFA and move on to the next step.
## 4. Read the Account's Balance
The balance job was successful and you can now read balance information. This is given by the `balance` and `available_balance` fields on the account object.
Make a `GET` request to the `/users/{user_guid}/members/{member_guid}/accounts/{account_guid}` endpoint. The response will include all the attributes of the specified account.
```shell theme={null}
curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/accounts/ACT-82a93692-f756-534f-9b2e-ad10a0f38462' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"account": {
"account_number": "****0001",
"apr": null,
"apy": null,
"available_balance": 500000,
"available_credit": null,
"balance": 500000,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2020-09-21T19:43:44Z",
"credit_limit": null,
"currency_code": null,
"day_payment_is_due": 12,
"death_benefit": null,
"guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
"holdings_value": null,
"id": "act-23445745",
"imported_at": "2023-02-24T09:01:25Z",
"institution_code": "mxbank",
"insured_name": null,
"interest_rate": null,
"is_closed": false,
"is_hidden": false,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"member_id": null,
"member_is_managed_by_user": true,
"metadata": null,
"minimum_balance": null,
"minimum_payment": null,
"name": "Checking",
"nickname": null,
"original_balance": null,
"pay_out_amount": null,
"payment_due_at": "2021-05-12T16:01:00Z",
"payoff_balance": null,
"premium_amount": null,
"routing_number": "005026788",
"started_on": null,
"subtype": null,
"total_account_value": null,
"type": "CHECKING",
"updated_at": "2023-02-24T09:01:25Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
}
}
```
**INFO**
There is another endpoint for reading an account provided for code convenience: `GET /users/{user_guid}/accounts/{account_guid}`.
You may also consider listing the details for all accounts associated with a user or a member:
`GET /users/{user_guid}/accounts`
`GET /users/{user_guid}/members/{member_guid}/accounts`