> ## Documentation Index > Fetch the complete documentation index at: https://docs.centryos.xyz/llms.txt > Use this file to discover all available pages before exploring further. # List Linked Accounts > Retrieve a paginated, filterable list of linked accounts for a business or end-user. ## Overview There are two endpoints for listing linked accounts depending on the caller context: | Endpoint | Auth | Use case | | -------------------------------------------------------- | ------------ | ------------------------------------------------------------ | | `GET /v1/business/:businessId/linked-accounts/:currency` | Access token | Dashboard / merchant portal — full detail, rich filters | | `GET /v1/ext/linked-accounts/:currency` | Access token | External API — account details with masked sensitive numbers | Both endpoints authenticate using the access token from [Generate Access Token](/guides/generate-access-token). *** ## Business Endpoint Returns all linked accounts for a business with enriched account details and support for multiple filters. ### Endpoint ``` GET {{LIQUIDITY_URL}}/v1/business/:businessId/linked-accounts/:currency ``` ### Auth ``` Authorization: Bearer {{accessToken}} ``` *** ### Path Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | -------------------------- | | `businessId` | string | Yes | UUID of the business | | `currency` | string | Yes | Currency code (e.g. `USD`) | *** ### Query Parameters | Parameter | Type | Required | Default | Description | | --------------- | ------- | -------- | ----------- | ------------------------------------------------------------------------- | | `accountType` | string | No | — | Filter by account type. See accepted values below. Alias for `optionType` | | `optionType` | string | No | — | Legacy alias for `accountType` — both work | | `email` | string | No | — | Partial case-insensitive match on counterparty email | | `search` | string | No | — | Partial case-insensitive match on counterparty name | | `last4` | string | No | — | Exact last-4 digits of card or bank account number (1–4 digits) | | `bank` | string | No | — | Partial case-insensitive match on bank name (e.g. `Chase`) | | `externalId` | string | No | — | Filter by external identifier | | `page` | integer | No | `1` | Page number | | `limit` | integer | No | `50` | Results per page | | `sortBy` | string | No | `createdAt` | Field to sort by | | `sortDirection` | string | No | `ASC` | Sort direction: `ASC` or `DESC` | #### `accountType` accepted values | Value | Description | | -------------------- | ------------------------------ | | `bank` | Local bank account (ACH / RTP) | | `card` | Debit or credit card | | `international_bank` | International wire / SWIFT | | `prepaid_card` | Prepaid card | *** ### Request Examples **Filter by account type:** ```bash theme={null} curl -X GET "{{LIQUIDITY_URL}}/v1/business/3e857814-91b1-4312-bb65-5e585227b6de/linked-accounts/USD?accountType=bank" \ -H "Authorization: Bearer {{accessToken}}" ``` **Cards ending in 4242:** ```bash theme={null} curl -X GET "{{LIQUIDITY_URL}}/v1/business/3e857814-91b1-4312-bb65-5e585227b6de/linked-accounts/USD?accountType=card&last4=4242" \ -H "Authorization: Bearer {{accessToken}}" ``` **Filter by bank name:** ```bash theme={null} curl -X GET "{{LIQUIDITY_URL}}/v1/business/3e857814-91b1-4312-bb65-5e585227b6de/linked-accounts/USD?bank=Chase" \ -H "Authorization: Bearer {{accessToken}}" ``` **Filter by counterparty email:** ```bash theme={null} curl -X GET "{{LIQUIDITY_URL}}/v1/business/3e857814-91b1-4312-bb65-5e585227b6de/linked-accounts/USD?email=john@example.com" \ -H "Authorization: Bearer {{accessToken}}" ``` **International banks, sorted newest first:** ```bash theme={null} curl -X GET "{{LIQUIDITY_URL}}/v1/business/3e857814-91b1-4312-bb65-5e585227b6de/linked-accounts/USD?accountType=international_bank&sortDirection=DESC&page=1&limit=20" \ -H "Authorization: Bearer {{accessToken}}" ``` *** ### Response (200) ```json theme={null} { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "currency": "USD", "optionType": "bank", "counterPartyName": "John Doe", "counterPartyEmail": "john@example.com", "counterPublicPartyEmail": null, "nickName": "My Chase Account", "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-06-01T08:00:00.000Z", "account": { "label": "Checking account", "lastFourDigits": "0042", "routing": "021000021", "bankName": "Chase", "accountType": "CHECKING", "routingType": "ACH" }, "recipientData": { "id": "7a70ab64-1d4a-4eb8-87fb-439efbbfa1dd", "type": "bank", "instrumentId": "I5XCcwNxmverGJQfhZUpmwJXaSuIpy", "nickName": "John Doe", "firstName": "John", "lastName": "Doe", "name": "John Doe", "email": "john@example.com", "bankName": "Chase", "accountNumber": "123456789042", "routingNumber": "021000021", "routingType": "ACH", "recipientAddress": "1, Texas", "recipientCity": "Austin", "recipientState": "TX", "recipientPostalCode": "73301" }, "wallet": { "id": "w1b2c3d4-e5f6-7890-abcd-ef1234567890", "balance": "5000.00", "disabled": false }, "entity": { "id": "3e857814-91b1-4312-bb65-5e585227b6de", "email": "owner@business.com", "externalIdentifier": "ext-123", "entityType": "BUSINESS" }, "application": null } ], "meta": { "page": 1, "pageSize": 50, "pageCount": 1, "total": 3 } } ``` *** ### `account` field — shape by `optionType` The `account` field is a parsed summary of the linked account. Its shape varies by type: ```json theme={null} { "label": "Checking account", "lastFourDigits": "0042", "routing": "021000021", "bankName": "Chase", "accountType": "CHECKING", "routingType": "ACH" } ``` ```json theme={null} { "label": "HSBC", "lastFourDigits": "1234", "bankName": "HSBC", "swiftOrBic": "HSBCGB2L", "country": "GB", "routingNumber": null } ``` ```json theme={null} { "label": "Visa ending 4242", "lastFourDigits": "4242", "cardBrand": "visa", "cardType": "credit" } ``` *** ### Response Fields | Field | Type | Description | | -------------------------------- | -------------- | ------------------------------------------------------------------ | | `data[].id` | string | Linked account UUID | | `data[].currency` | string | Currency code | | `data[].optionType` | string | Account type: `bank`, `card`, `international_bank`, `prepaid_card` | | `data[].counterPartyName` | string | Counterparty display name | | `data[].counterPartyEmail` | string | Counterparty email address | | `data[].counterPublicPartyEmail` | string \| null | Public-facing email, if set | | `data[].nickName` | string \| null | User-defined nickname | | `data[].createdAt` | string | ISO 8601 creation timestamp | | `data[].updatedAt` | string | ISO 8601 last-updated timestamp | | `data[].account` | object \| null | Parsed account summary (shape varies by `optionType`) | | `data[].recipientData` | object \| null | Full raw metadata stored for this account | | `data[].wallet` | object | Associated wallet `{ id, balance, disabled }` | | `data[].entity` | object | Owning entity `{ id, email, externalIdentifier, entityType }` | | `data[].application` | object \| null | Application token details if linked via token | | `meta.page` | integer | Current page | | `meta.pageSize` | integer | Results per page | | `meta.pageCount` | integer | Total pages | | `meta.total` | integer | Total matching records | *** ### Error Responses | Status | Body | Cause | | ------ | ------------------------------------------------- | -------------------------------------------------- | | `401` | `{ "message": "Unauthorized", "success": false }` | Missing or malformed `Authorization` header | | `400` | `{ "message": "...", "success": false }` | Business metadata lookup failed or invalid request | *** ## External Endpoint Returns linked accounts for an end-user with masked sensitive numbers and stripped internal fields. ### Endpoint ``` GET {{LIQUIDITY_URL}}/v1/ext/linked-accounts/:currency ``` ### Auth ``` Authorization: Bearer {{accessToken}} ``` ### Path Parameters | Parameter | Type | Required | Description | | ---------- | ------ | -------- | -------------------------- | | `currency` | string | Yes | Currency code (e.g. `USD`) | ### Query Parameters | Parameter | Type | Required | Default | Description | | ------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------- | | `limit` | integer | No | `10` | Results per page | | `page` | integer | No | `1` | Page number | | `externalId` | string | No | — | Filter by external entity ID | | `accountType` | string | No | — | Filter by account type: `bank`, `card`, `international_bank`, `prepaid_card`. Alias: `optionType` | | `optionType` | string | No | — | Legacy alias for `accountType` | | `email` | string | No | — | Partial case-insensitive match on counterparty email | | `last4` | string | No | — | Exact last-4 digits of card or bank account number (1–4 digits) | | `bank` | string | No | — | Partial case-insensitive match on bank name (e.g. `Chase`) | ### Request ```bash theme={null} curl -X GET "{{LIQUIDITY_URL}}/v1/ext/linked-accounts/USD?limit=10&page=1" \ -H "Authorization: Bearer {{accessToken}}" ``` ### Response (200) ```json theme={null} { "success": true, "data": [ { "id": "ffdda9bc-a142-4b39-b546-52b15c91d94c", "currency": "USD", "optionType": "bank", "counterPartyName": "Johnny Walker", "counterPartyEmail": "johnny@example.com", "counterPublicPartyEmail": null, "nickName": "Johnny Walker", "createdAt": "2026-03-13T15:08:59.717Z", "account": { "routing": "****0021", "bankName": "JPMORGAN CHASE", "accountType": null, "routingType": "ACH" }, "recipientData": { "id": "7a70ab64-1d4a-4eb8-87fb-439efbbfa1dd", "type": "bank", "instrumentId": "I5XCcwNxmverGJQfhZUpmwJXaSuIpy", "nickName": "Johnny Walker", "firstName": "Johnny", "lastName": "Walker", "name": "Johnny Walker", "email": "johnny@example.com", "bankName": "JPMORGAN CHASE", "accountNumber": "****3591", "routingNumber": "****0021", "routingType": "ACH", "recipientAddress": "1, Texas", "recipientCity": "Austin", "recipientState": "TX", "recipientPostalCode": "73301" } } ], "meta": { "page": 1, "pageSize": 10, "pageCount": 2, "total": 17 } } ``` ### Response Fields | Field | Type | Description | | -------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data[].id` | string | Linked account UUID — use this for withdrawal requests | | `data[].currency` | string | Currency code | | `data[].optionType` | string | Account type: `bank`, `card`, `international_bank`, `prepaid_card` | | `data[].counterPartyName` | string | Recipient display name | | `data[].counterPartyEmail` | string | Counterparty email address | | `data[].counterPublicPartyEmail` | string \| null | Public-facing email, if set | | `data[].nickName` | string | User-defined nickname (may be empty) | | `data[].createdAt` | string | ISO 8601 creation timestamp | | `data[].account` | object \| null | Parsed account summary. `routing` masked to last 4 digits (`****XXXX`) | | `data[].recipientData` | object \| null | Account metadata — `accountNumber` and `routingNumber` masked to last 4 digits; `provider`, `identityId`, `encryptedCardNumber`, `cardExpirationDate` stripped | | `meta.page` | integer | Current page | | `meta.pageSize` | integer | Results per page | | `meta.pageCount` | integer | Total pages | | `meta.total` | integer | Total linked accounts | ## Notes * Use `data[].id` from either endpoint as the `linkedAccountId` when creating a withdrawal * `last4` filter matches digits stored in `metadata.account` or `metadata.cardNumber` — it will not match accounts where neither field is populated * `bank` filter searches `metadata.bankName`; populated for `bank` and `international_bank` types