View as Markdown

Accounts API

The Accounts API provides account listing, and account balance APIs.

Base URL: https://interact-uat.hsbc.com/accounts-service
GET /v1/accounts

List accounts

Returns account metadata (identity fields only - no balance amounts) for every account visible to the authenticated customer.

Accounts are de-duplicated by unformattedAccountNumber and sorted ascending by that value.

Query parameters

fields is optional: a comma-separated list of extra field names taken from FieldSelectionMapping.ACCOUNTS_FIELD_MAP. Unknown names → 400. Balance-amount fields are never returned here.

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 so the service knows which customer to query; cookie-authenticated (C2B) callers may omit both.
  • hsbc-correlation-id — optional, numeric only.
  • X-HSBC-Entitled-Accounts is not read by this endpoint (only by /v1/account-balances).

Example (B2B, UAT)

curl --request GET \
  --url 'https://interact.hsbc.com/accounts-service/v1/accounts' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <B2B_JWT>' \
  --header 'X-HSBC-CustId: GBHBEUNEOTEST' \
  --header 'x-hsbc-channel-id: nio-api' \
  --header 'hsbc-correlation-id: 1234567890'
Requires authentication: bearerAuth (header) or neosessionCookie (cookie) or neoSessionHeader (header)

Parameters

NameInDescription
fields
string 		query Optional. Comma-separated list of additional field names to include in the response. Unknown names return 400. Allowed values: accountTitle, accountTypeDescription, bic, iban, realAccountNumber, masterAccountNumber, bankName, institutionDescription, currencyDescription, countryDescription, accountStatus, accountCreatedDate, childAccountCode, accountBosType, nraIndicator, insurableIndicator, realTimeOrPreviousStatus, authorityCodes, statementEnabled, cinHub, uniqueApiCode, accountFormatType, documentControlNumber, productType, statementAvailable, detailedBalancesEnabled, reportingType
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.

Responses

  • 200 Accounts 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.
  • 403 Error propagated from an upstream dependency. GET /v1/accounts propagates the upstream status code and body; /v1/account-balances instead degrades to an empty result set except for 401.
  • 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.
GET /v1/account-balances

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

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-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
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
GET /health

Service health check

Health/readiness probe. Note: this endpoint is served from the server root (e.g. https://host:port/health), i.e. outside the /accounts-service/ base path shown in servers. No parameters and no authentication are required.

Responses

  • 200 Service is healthy
  • 503 Service is unavailable
  • 400 Bad request — invalid or missing parameters
  • 401 Unauthorized — authentication credentials missing or invalid
  • 403 Forbidden — insufficient permissions for this resource
  • 500 Internal server error