List Linked Accounts

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.

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:

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:

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:

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:

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:

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)

{
  "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:

bank

{
  "label": "Checking account",
  "lastFourDigits": "0042",
  "routing": "021000021",
  "bankName": "Chase",
  "accountType": "CHECKING",
  "routingType": "ACH"
}

international_bank

{
  "label": "HSBC",
  "lastFourDigits": "1234",
  "bankName": "HSBC",
  "swiftOrBic": "HSBCGB2L",
  "country": "GB",
  "routingNumber": null
}

card / prepaid_card

{
  "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

curl -X GET "{{LIQUIDITY_URL}}/v1/ext/linked-accounts/USD?limit=10&page=1" \
  -H "Authorization: Bearer {{accessToken}}"

Response (200)

{
  "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

Getting Started

Authentication

Account

Wallets

Transactions

Payin

Payout

Linked Accounts

Webhooks

List Linked Accounts

Overview

Business Endpoint

Endpoint

Auth

Path Parameters

Query Parameters

`accountType` accepted values

Request Examples

Response (200)

`account` field — shape by `optionType`

Response Fields

Error Responses

External Endpoint

Endpoint

Auth

Path Parameters

Query Parameters

Request

Response (200)

Response Fields

Notes

Getting Started

Authentication

Account

Wallets

Transactions

Payin

Payout

Linked Accounts

Webhooks

Documentation Index

​Overview

​Business Endpoint

​Endpoint

​Auth

​Path Parameters

​Query Parameters

​accountType accepted values

​Request Examples

​Response (200)

​account field — shape by optionType

​Response Fields

​Error Responses

​External Endpoint

​Endpoint

​Auth

​Path Parameters

​Query Parameters

​Request

​Response (200)

​Response Fields

​Notes

Overview

Business Endpoint

Endpoint

Auth

Path Parameters

Query Parameters

`accountType` accepted values

Request Examples

Response (200)

`account` field — shape by `optionType`

Response Fields

Error Responses

External Endpoint

Endpoint

Auth

Path Parameters

Query Parameters

Request

Response (200)

Response Fields

Notes