Retrieve the current balance of an external account linked to a specific customer profile.
Get External Account Balance
The GET /netevia/externalAccountBalance/{profileId} endpoint retrieves the current balance of an external bank account linked to a specific customer profile. It returns the balance amount, currency, and the date/time the balance was last recorded. External accounts must first be connected via Finicity or Plaid before this endpoint can return balance data.
Endpoint
GET /netevia/externalAccountBalance/{profileId}
Authentication
Bearer token required. Obtain via:
POST https://api.banking.netevia.dev/api/auth/v2Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.
When to use
Use this endpoint to display an up-to-date external account balance to a customer within your application, for example on a financial overview screen or before initiating an ACH transfer. This is typically called after a customer has linked an external account via Finicity or Plaid and you need to show real-time or last-fetched balance data. It is relevant for personal customers who have connected external accounts to their Netevia profile.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| profileId | integer (int32) | Yes | The unique numeric identifier of the customer profile whose external account balance is being queried. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| financialAccountId | string | No | The identifier of the specific financial account to query. Use this to scope the balance lookup to a particular linked account when multiple external accounts are connected. |
| provider | string | No | The external account provider used to link the account. Accepted values: FINICITY, PLAID. |
Response
200 OK
| Field | Type | Description |
|---|---|---|
| date | string (date-time) | The date and time when the balance was last retrieved or recorded. Nullable. |
| value | number (double) | The current balance of the external account. Nullable. |
| currency | string | The ISO currency code for the account balance (e.g., USD). Nullable. |
{
"date": "2026-06-08T14:32:00Z",
"value": 2450.75,
"currency": "USD"
}Error Codes
| Code | When it happens |
|---|---|
| 400 | The profileId is missing, not a valid integer, or the provider value is not one of the accepted enum values (FINICITY, PLAID). |
| 401 | Token missing, expired, or invalid. |
| 403 | Insufficient permissions — the authenticated partner does not have access to the specified profile. |
| 404 | No customer profile found for the given profileId, or no external account is linked for the specified financialAccountId or provider. |
| 500 | Internal server error. |
Common Mistakes
- Omitting
providerorfinancialAccountIdwhen the profile has multiple external accounts linked across different providers — this may return unexpected or ambiguous results. - Passing a non-integer value for
profileId(e.g., a UUID string) — the field expects anint32value. - Querying balance for an external account that has not yet completed underwriting verification; the account must be active before balance data is available.
- Using an incorrect
providervalue (e.g.,"Plaid"instead of"PLAID") — the enum is case-sensitive.
Related Endpoints
GET /netevia/externalAccounts/{profileId}— List all external accounts linked to a customer profilePOST /netevia/externalAccount/{profileId}— Link a new external account via Finicity or PlaidPOST /netevia/transfer/ach— Initiate an ACH transfer from a linked external account
Example
curl -X GET "https://api.banking.netevia.dev/netevia/externalAccountBalance/98765?financialAccountId=ext-acct-001&provider=PLAID" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json"