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

​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