List Beneficiaries

Retrieve a paginated list of your registered beneficiaries. Use filters to narrow results by account type, entity type, currency, or other attributes. Results support cursor-based pagination for iterating through large datasets.
Request Parameters
limitinteger
Number of records to return per page. Range: 1–100. Defaults to 20 if omitted.
cursorstring
Pagination cursor from the previous response's nextCursor or prevCursor. Omit for the first page.
accountTypestring
Filter by account type.

Valid Values:

BANK_ACCOUNT — Bank account.
DIGITAL_WALLET — Digital wallet.
entityTypestring
Filter by entity type.

Valid Values:

COMPANY — Corporate entity.
PERSONAL — Individual.
relationTypestring
Filter by relationship type.

Valid Values:

SAME_NAME — Same-name transfer.
THIRD_PARTY — Third-party transfer.
RELATED_MERCHANT — Related merchant transfer.
paymentTypestring
Filter by payment rail.

Valid Values:

LOCAL — Local clearing network.
CROSS — Cross-border transfer.
nicknamestring
Filter by display name. Supports fuzzy (partial) matching. Max 70 characters.
accountNamestring
Filter by account holder name.
accountNumberstring
Filter by bank account number. Supports fuzzy matching.
ibanstring
Filter by IBAN.
certificateNostring
Filter by certificate number.
currencyListarray
Filter by one or more currencies. Each element is a three-letter ISO 4217 code.
referenceBeneficiaryIdstring
Your internal reference ID for this beneficiary.
Response Parameters
resultResult
See Result.
itemsarray
Beneficiary records. Maximum 100 items per page.
Show child parametersShow child parameters
nextCursorstring
Cursor to retrieve the next page. null when on the last page.
prevCursorstring
Cursor to retrieve the previous page. null when on the first page.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
UN_SUPPORT_BUSINESSFUnsupported business.Verify all parameter values are within supported ranges and retry.
CURRENCY_NOT_SUPPORTEDFThe currency is not supported.Use a supported currency code following the ISO 4217 standard. See Data Types for the list of supported currencies.
BENEFICIARY_NOT_EXISTFThe beneficiary does not exist.Verify the beneficiary ID is correct. Use List Beneficiaries to find the right ID.
Definition
POST /api/open/v1/beneficiaries/list
Request
{
"limit": 10,
"accountType": "BANK_ACCOUNT",
"entityType": "PERSONAL",
"relationType": "THIRD_PARTY"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"items": [
  {
    "id": "20260401123123123",
    "status": "ACTIVE",
    "createdAt": "2026-03-30T12:08:56+08:00",
    "nickname": "Supplier A",
    "currency": "USD",
    "region": "US",
    "paymentType": "LOCAL",
    "accountType": "BANK_ACCOUNT",
    "entityType": "PERSONAL",
    "relationType": "THIRD_PARTY",
    "classificationCode": "0001",
    "bankDetails": {
      "accountNumber": "50001**121",
      "accountHolderName": {
        "fullName": "TestName"
      },
      "routingNumber": "0210000****21",
      "bankName": "JPMorgan Chase Bank, NA",
      "beneficiaryRegion": "US",
      "beneficiaryState": "CA",
      "beneficiaryPostalCode": "90028"
    },
    "city": "Los Angeles",
    "address": "6767 Hollywood Test Address"
  }
],
"prevCursor": null,
"nextCursor": "eyJpZCI6IjIwMjYwNDAxMTIzMTIzMTIzIn0="
}