List account balances

Deprecation notice: This endpoint is expected to be deprecated in a future release. New integrations should use POST /v1/account-balances, which accepts the entitled accounts list in the request body and avoids header size limitations.

Returns balance data for accounts visible to the authenticated customer. Bank accounts and corporate card accounts are fetched in parallel and merged, then sorted by accountType then accountId.

Query parameters (all optional)

filter — all or omitted → every account; any other value → only accounts that have a non-empty interimAvailableAmount.
fields — extra fields from FieldSelectionMapping.BALANCES_FIELD_MAP; prefix with ~ for derived fields (e.g. ~soloDisplayBalanceAmountFXAdjusted). Unsupported derived names are logged and ignored.
fx_target_currency — ISO 4217 target currency, used only by the FX-adjusted derived field.

Headers

Auth: exactly one of Authorization: Bearer, neosession cookie or X-Neo-Session.
X-HSBC-Entitled-Accounts — mandatory JSON array; without it (or with all entries skipped) the response will contain no bank-account balances. Entitled accounts are forwarded to the upstream balances call. A malformed value is logged and treated as an empty list (no error).
x-hsbc-channel-id: nio-api and x-hsbc-custid are mandatory for B2B (Bearer-token) callers; cookie-authenticated (C2B) callers may omit both.
hsbc-correlation-id — optional, numeric only.

Resilience

Upstream account/card failures are caught and returned as an empty list (still 200), except an upstream 401, which is re-thrown as 401 UnAuthorized Access in the standard JSON error envelope.

Example (B2B, UAT)

curl --request GET \
  --url 'https://interact.hsbc.com/accounts-service/v1/account-balances?filter=all' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <B2B_JWT>' \
  --header 'X-HSBC-CustId: GBHBEUNEOTEST' \
  --header 'X-HSBC-Entitled-Accounts: [{"accCntryCode":"GB","accInst":"HBEU","accType":"CA","unFmtdAccNo":"22946414048725"}]' \
  --header 'x-hsbc-channel-id: nio-api' \
  --header 'hsbc-correlation-id: 1234567890'

Requires authentication: bearerAuth (header) or neosessionCookie (cookie) or neoSessionHeader (header)

Parameters

Name	In	Description
filter string	query	Optional. `all` (or omitted) returns every account. Any other value returns only accounts that have a non-empty `interimAvailableAmount`. The value is compared case-insensitively.
fields string	query	Optional. Comma-separated list of additional field names to include. Prefix with `~` for derived fields (e.g. `~soloDisplayBalanceAmountFXAdjusted`). Unsupported derived fields are ignored. Unknown names return `400`. All identity fields allowed on `/v1/accounts` are also supported here. Additional balance-specific fields: `currentAvailableBalance`, `currentAvailableBalanceDate`, `currentAvailableBalanceWithCF`, `currentAvailableBalanceWithCFDate`, `currentBookedBalance`, `currentBookedBalanceDate`, `currentBookedBalanceWithCF`, `currentBookedBalanceWithCFDate`, `projectedAvailableBalance`, `projectedAvailableBalanceDate`, `projectedAvailableBalanceWithCF`, `projectedAvailableBalanceWithCFDate`, `projectedBookedBalance`, `projectedBookedBalanceDate`, `projectedBookedBalanceWithCF`, `openingAvailableBalance`, `openingAvailableBalanceDate`, `openingAvailableBalanceWithCF`, `openingBookedBalance`, `openingBookedBalanceDate`, `openingBookedBalanceWithCF`, `balanceAsAt` Derived fields: `~soloDisplayBalanceAmountFXAdjusted`
fx_target_currency string	query	Optional (conditionally required). ISO 4217 target currency for FX conversion; only used when the `~soloDisplayBalanceAmountFXAdjusted` derived field is requested.
hsbc-correlation-id string	header	Optional. Correlation ID for end-to-end tracing. Honoured only when non-blank and fully numeric; anything else is replaced by a generated timestamp-based ID. Forwarded upstream as `x-hsbc-request-correlation-id`.
X-HSBC-Entitled-Accounts required string	header	Mandatory for `GET /v1/account-balances` (ignored by `/v1/accounts` and by the POST variant, which uses `entitledAccounts` in the request body instead). JSON array of entitled accounts; each object needs `accCntryCode`, `accInst`, `accType`, `unFmtdAccNo` (entries without `unFmtdAccNo` are skipped). Without this header (or with all entries skipped) the response will contain no bank-account balances. Malformed JSON is logged and treated as an empty list — no error is returned, but use the POST variant for large lists.
x-hsbc-channel-id required string	header	Mandatory for B2B (`nio-api`) callers. Must be `nio-api` and be accompanied by a non-blank `x-hsbc-custid` for the B2B customer override to apply. When it applies, the service forces the nio-api TPID and forwards `x-hsbc-channel-id: NEO` upstream. Only cookie-based (C2B, `neosession`) callers may omit this header — the inbound value is otherwise forwarded upstream as-is.
x-hsbc-custid required string	header	Mandatory for B2B (`nio-api`) callers. Customer ID to query, used instead of the session subject when `x-hsbc-channel-id` is `nio-api`. Header names are case-insensitive, so `X-HSBC-CustId` is equivalent. Without it a B2B Bearer call falls back to the token subject (a profile ID) and will typically return no accounts. Only cookie-based (C2B, `neosession`) callers may omit this header.

Responses

200 Account balances retrieved successfully
400 Invalid request. Returned as JSON for unknown fields values, an invalid JSON body or invalid requestedAccountIds. Exception: when both a neosession token and an Authorization header are supplied, the session security check aborts with text/plain Ambiguous authentication credentials.
401 Missing or invalid credentials. * Rejected by the session security check → text/plain body 401 Unauthorized with WWW-Authenticate: Bearer. * Upstream 401 while fetching accounts/cards → JSON envelope with message UnAuthorized Access.
429 Too many requests. The caller has exceeded the rate limit for this endpoint.
500 Unexpected server error. The upstream/exception message and a generated errorId are returned in the envelope.
403 Forbidden — insufficient permissions for this resource