# Retrieve the current balance for a link

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.

Endpoint: POST /api/br/balances/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `omit` (string)
    Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article.

  - `fields` (string)
    Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article.

## Request fields (application/json):

  - `link` (string, required)
    The link.id you want to retrieve information for.
    Example: "c81a1dea-6dd6-4999-8b9f-541ee8197058"

  - `account_id` (string)
    The Belvo account.id you want to retrieve information for.
    Example: "e2cdb621-f44a-4558-89f6-8ab2a57add7a"

  - `save_data` (boolean)
    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: true

## Response 200 fields (application/json):

  - `id` (string, required)
    The unique identifier created by Belvo used to reference the current balance.
    Example: "0b94bdf9-3719-43a9-81e7-be95d2318595"

  - `link` (string, required)
    The unique identifier of the link that this balance belongs to.
    Example: "0b94bdf9-3719-43a9-81e7-be95d2318595"

  - `account_id` (string, required)
    The Belvo account.id that this balance belongs to.
    Example: "c4bfecf9-4eb6-4920-9f9f-e1f1e60ef321"

  - `account_internal_identification` (string, required)
    The institution's internal identification for the account.
    Example: "92792126019929279212650822221989319252576"

  - `collected_at` (string, required)
    The ISO-8601 timestamp when the data point was collected.
    Example: "2024-05-21T08:32:00Z"

  - `created_at` (string, required)
    The ISO-8601 timestamp of when the data point was created in Belvo's database.
    Example: "2024-05-21T08:32:00Z"

  - `last_updated_at` (string, 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.
    Example: "2021-05-21T08:30:00Z"

  - `currency` (string, required)
    The three-letter currency code (ISO-4217).
    Example: "USD"

  - `available` (number, required)
    The available account balance.
    Example: 1000.02

  - `blocked` (number, required)
    The amount that is currently blocked due to, for example, pending transactions.
    Example: 1000.02

  - `automatically_invested` (number, required)
    The amount that is automatically invested (as agreed upon with the institution).
    Example: 1000.02

## Response 201 fields (application/json):

  - `id` (string, required)
    The unique identifier created by Belvo used to reference the current balance.
    Example: "0b94bdf9-3719-43a9-81e7-be95d2318595"

  - `link` (string, required)
    The unique identifier of the link that this balance belongs to.
    Example: "0b94bdf9-3719-43a9-81e7-be95d2318595"

  - `account_id` (string, required)
    The Belvo account.id that this balance belongs to.
    Example: "c4bfecf9-4eb6-4920-9f9f-e1f1e60ef321"

  - `account_internal_identification` (string, required)
    The institution's internal identification for the account.
    Example: "92792126019929279212650822221989319252576"

  - `collected_at` (string, required)
    The ISO-8601 timestamp when the data point was collected.
    Example: "2024-05-21T08:32:00Z"

  - `created_at` (string, required)
    The ISO-8601 timestamp of when the data point was created in Belvo's database.
    Example: "2024-05-21T08:32:00Z"

  - `last_updated_at` (string, 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.
    Example: "2021-05-21T08:30:00Z"

  - `currency` (string, required)
    The three-letter currency code (ISO-4217).
    Example: "USD"

  - `available` (number, required)
    The available account balance.
    Example: 1000.02

  - `blocked` (number, required)
    The amount that is currently blocked due to, for example, pending transactions.
    Example: 1000.02

  - `automatically_invested` (number, required)
    The amount that is automatically invested (as agreed upon with the institution).
    Example: 1000.02

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 428 fields (application/json):

  - `code` (string)
    A unique error code (token_required) that allows you to classify and handle the error programmatically.
ℹ️ Check our DevPortal for more information on how to handle 428 token_required errors.
    Example: "token_required"

  - `message` (string)
    A short description of the error. 
For token_required errors, the description is:
  
  - A MFA token is required by the institution to login.
    Example: "A MFA token is required by the institution to login"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `session` (string)
    A 32-character unique ID of the login session (matching a regex pattern of: [a-f0-9]{32}).
    Example: "2675b703b9d4451f8d4861a3eee54449"

  - `expiry` (integer)
    Session duration time in seconds.
    Example: 9600

  - `link` (string)
    Unique identifier created by Belvo, used to reference the current
Link.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `token_generation_data` (object)
    Details on how to generate the token.

  - `token_generation_data.instructions` (string)
    Instructions for token generation.
    Example: "Use this code to generate the token"

  - `token_generation_data.type` (string)
    Type of the data to generate the token (QR code, numeric
challenge).
    Example: "numeric"

  - `token_generation_data.value` (string)
    Value to use to generate the token.
    Example: "12345"

  - `token_generation_data.expects_user_input` (boolean)
    Indicates whether the user needs to provide input in order to complete the authentication.
When set to false, your user may need to:
- confirm the login on another device
- scan a QR code
You will still need to make a PATCH call to complete the request.
    Example: true

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"