View as Markdown

Accounts API

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.