BEbelvo
Balances

Retrieve the current balance for a link

Changed on

Retrieve the current account balance for all checking and savings accounts for an existing link. We recommend also sending the account.id so that you receive balances for a specific account.

post/api/br/balances/

Request

Query parameters

omitstring

Omit certain fields from being returned in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

fieldsstring

Return only the specified fields in the response. For more information, see our <a href="https://developers.belvo.com/docs/searching-and-filtering" target="_blank">Filtering responses</a> DevPortal article.

Request body

linkstring uuid required

The link.id you want to retrieve information for.

account_idstring uuid

The Belvo account.id you want to retrieve information for.

save_databoolean

Indicates whether or not to persist the data in Belvo. By default, this is set to true and we return a 201 Created response.

When set to false, the data won't be persisted and we return a 200 OK response.

Example request

{
  "link": "c81a1dea-6dd6-4999-8b9f-541ee8197058",
  "account_id": "e2cdb621-f44a-4558-89f6-8ab2a57add7a",
  "save_data": true
}

Response

OK - Balance Retrieved (when save_data=false)

idstring uuid required

The unique identifier created by Belvo used to reference the current balance.

linkstring uuid required

The unique identifier of the link that this balance belongs to.

account_idstring uuid required

The Belvo account.id that this balance belongs to.

account_internal_identificationstring required

The institution's internal identification for the account.

collected_atstring date-time required

The ISO-8601 timestamp when the data point was collected.

created_atstring date-time required

The ISO-8601 timestamp of when the data point was created in Belvo's database.

last_updated_atstring date-time required

The ISO-8601 timestamp of when this balance was last updated by the institution.

🚧 Warning

The last_updated_at parameter depends on how the institution processes (or stores) data. In the case that the institution stores data synchronously (that is, as soon as a transaction occurs, the balance us updated), then the last_updated_at will reflect the balance in near real time. In the case that the institution stores data asynchronously (that is, it retrieves data in bulk and then updates the balance), the balance information can refer to hours or days ago. Additionally, in the case that the institution cannot provide the specific time (due to an internal error), the institution may provide an overall time where they last refreshed the account and balance information.

currencystring required

The three-letter currency code (ISO-4217).

availablenumber float required

The available account balance.

blockednumber float required

The amount that is currently blocked due to, for example, pending transactions.

automatically_investednumber float required

The amount that is automatically invested (as agreed upon with the institution).

Example response

[
  {
    "id": "0b94bdf9-3719-43a9-81e7-be95d2318595",
    "link": "0b94bdf9-3719-43a9-81e7-be95d2318595",
    "account_id": "c4bfecf9-4eb6-4920-9f9f-e1f1e60ef321",
    "account_internal_identification": "92792126019929279212650822221989319252576",
    "collected_at": "2024-05-21T08:32:00Z",
    "created_at": "2024-05-21T08:32:00Z",
    "last_updated_at": "2021-05-21T08:30:00Z",
    "currency": "USD",
    "available": 1000.02,
    "blocked": 1000.02,
    "automatically_invested": 1000.02,
    "reserved_balances": [
      {
        "name": "Cofrinho",
        "identification": "d78fc4e5-37ca-4da3-adf2-9b082bf92280",
        "amounts": [
          {
            "amount": 1565.51,
            "currency": "BRL",
            "remuneration": {
              "post_fixed_rate": 1.2,
              "rate_type": "LINEAR",
              "rate_periodicity": "ANUAL",
              "calculation_base": "DIAS_UTEIS",
              "indexer": "CDI"
            }
          }
        ]
      }
    ]
  }
]

Changes

  • acb784e42ca0Revision changes
    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status