Refresh and Get External Account Balance

This endpoint retrieves the current balance of a linked external financial account. It refreshes the data from the external account in real time, ensuring users have access to the most up-to-date balance information. The response includes the balance value, currency type, and the timestamp when the balance was last refreshed.

Endpoint

GET /api/financialAccounts/external/balance

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to Use

Use this endpoint when a customer wants to view the current balance of an external account they have linked to their Netevia profile via Finicity or Plaid. This is especially useful for personal customers who manage funds across multiple financial institutions and need a consolidated, real-time view of their account balances. Call this endpoint before initiating an ACH transfer from an external account to verify sufficient funds are available.

Query Parameters

Response

200 OK

{
  "date": "2026-06-08T14:32:00Z",
  "value": 2450.75,
  "currency": "USD"
}

Error Codes

Common Mistakes

• Omitting financialAccountId when the authenticated profile has multiple linked external accounts — the API may return an ambiguous result or an error. Always supply the specific account ID.
• Using the ID of an internal Netevia financial account instead of an external account ID. External accounts are those added via Finicity or Plaid and have a distinct identifier.
• Not refreshing the token before making the request — Bearer tokens expire after 10 minutes. Ensure the token is valid before calling this endpoint.
• Expecting a non-null value immediately after linking a new external account. The balance may be null if the external provider has not yet returned data.

Related Endpoints

• GET /api/financialAccounts/external — List all external financial accounts linked to the customer's profile
• POST /api/financialAccounts/external — Link a new external financial account via Finicity or Plaid
• POST /api/transfers/ach — Initiate an ACH transfer from a linked external account

Example

curl -X GET "https://api.banking.netevia.dev/api/financialAccounts/external/balance?financialAccountId=fa_ext_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"