# 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)
```bash
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

| Name | In | Type | Description |
|---|---|---|---|
| `fields` | query | string | 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` | header | string | 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` | header | string *(required)* | 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` | header | string *(required)* | 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.


#### Examples

```bash
curl "https://interact-uat.hsbc.com/accounts-service/v1/accounts?fields=bic,iban,accountStatus,accountCreatedDate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "hsbc-correlation-id: 1234567890" \
  -H "x-hsbc-channel-id: nio-api" \
  -H "x-hsbc-custid: GBHBEUNEOTEST"
```

```javascript
const response = await fetch("https://interact-uat.hsbc.com/accounts-service/v1/accounts?fields=bic,iban,accountStatus,accountCreatedDate", {
  headers: {
      "Authorization": "Bearer YOUR_TOKEN",
      "hsbc-correlation-id": "1234567890",
      "x-hsbc-channel-id": "nio-api",
      "x-hsbc-custid": "GBHBEUNEOTEST"
  },
});

const data = await response.json();
```

```python
import requests

url = "https://interact-uat.hsbc.com/accounts-service/v1/accounts?fields=bic,iban,accountStatus,accountCreatedDate"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "hsbc-correlation-id": "1234567890",
    "x-hsbc-channel-id": "nio-api",
    "x-hsbc-custid": "GBHBEUNEOTEST",
}

response = requests.get(url, headers=headers)
print(response.json())
```

```java
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://interact-uat.hsbc.com/accounts-service/v1/accounts?fields=bic,iban,accountStatus,accountCreatedDate"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .header("hsbc-correlation-id", "1234567890")
    .header("x-hsbc-channel-id", "nio-api")
    .header("x-hsbc-custid", "GBHBEUNEOTEST")
    .GET()
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

#### Example response

```json
{
  "data": {
    "accounts": [
      {
        "countryCode": "GB",
        "institutionCode": "HBEU",
        "accountType": "CA",
        "accountId": "22946414048725",
        "formattedAccountNumber": "229464-14048725",
        "unformattedAccountNumber": "22946414048725",
        "accountName": "NEO TEST ACCOUNT",
        "currencyCode": "GBP",
        "bic": "MIDLGB22XXX",
        "iban": "GB29HBUK40229412345678",
        "accountStatus": "ACTIVE",
        "accountCreatedDate": "2019-04-12T00:00:00Z"
      }
    ]
  },
  "meta": {
    "success": true,
    "message": "Accounts retrieved successfully",
    "status": 200,
    "timestamp": "2026-08-27T09:00:00.123Z",
    "pagination": {
      "offset": 0,
      "limit": 1000,
      "count": 1,
      "totalResults": 1
    }
  }
}
```