View as Markdown

Accounts API

Base URL: https://interact-uat.hsbc.com/accounts-service
POST /v1/account-balances

List account balances

Same behaviour as GET /v1/account-balances, except the entitled-account list is supplied in the JSON body instead of the X-HSBC-Entitled-Accounts header (avoids header size limits), plus an optional requestedAccountIds selection.

Headers

  • Auth: exactly one of Authorization: Bearer, neosession cookie or X-Neo-Session.
  • 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.
  • The header X-HSBC-Entitled-Accounts is ignored by this operation — use the body instead.

Body

The body is technically optional ({} or no body → empty entitled list), but omitting entitledAccounts (or supplying only unusable entries) will return no bank-account balances, so it should be treated as mandatory for a meaningful response. Parsing rules :

  • Malformed JSON → 400 Invalid request payload.
  • entitledAccounts — recommended/mandatory array; entries without unFmtdAccNo are skipped, other properties default to "".
  • requestedAccountIds — optional; must be an array of strings, each trimmed, upper-cased and stripped of spaces/-//, then matched against [A-Z0-9]{1,128}. The list must be non-empty, ≤ 100 entries and unique, otherwise 400.
Requires authentication: bearerAuth (header) or neosessionCookie (cookie) or neoSessionHeader (header)

Parameters

NameInDescription
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-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.

Request Body application/json

FieldDescription
entitledAccounts required
array 		Mandatory for a non-empty response. Entitled accounts to query. An empty or omitted array returns no bank-account balances. Entries without unFmtdAccNo are silently skipped.
requestedAccountIds
array 		Optional. Narrows the returned accounts. Values are trimmed, upper-cased and have spaces, - and / removed before validation against [A-Z0-9]{1,128}. Must be a non-empty array of 1-100 unique strings, otherwise 400.

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