--- title: "Retrieve beneficiaries" method: GET path: "/beneficiaries" tags: ["Beneficiaries"] --- # Retrieve beneficiaries `GET /beneficiaries` The ability to get the details of beneficiaries using various pieces of information, e.g. using customer ID, retrieve all beneficiaries created by that customer. Can get details of one particular beneficiary based on the unique beneficiary reference number. ## Query parameters - `id` string[] — ID of Customer(s) to fetch - `customerId` string — Filter by Customer Id - `q` string — Partial name of beneficiary or Scan Details Or IBAN Or external referenceOr default reference to search for. Deprecated use validForAccount, orSortCode, orAccountNumber, orIban, orName, orExternalReference, orDefaultReference instead - `modifiedSince` string — Beneficiaries modified after this date time - `hasExternalReference` boolean — Filter by existence of external reference - `externalReference` string — External reference for beneficiary - `iban` string — IBAN - `abaRoutingNumber` string — abaRoutingNumber - `currency` 'GBP' | 'EUR' | 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'FJD' | 'FKP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SLE' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'SHP' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL' — Currency - `qualifier` string[] — A list of external qualifiers - `state` string[] — Approval item state(s) to filter by - `validForAccount` string — Source account BID. Limit results to beneficiaries which would be valid recipients of payments from the given account (e.g. IBAN can’t be paid from GBP account, SCAN can’t be paid from non-GBP account). The specified account must be accessible to the user - `sortOrder` string — Sort order - `sortField` string — Sort by field, This defaults to name if not present - `orSortCode.type` 'WORD_MATCH' | 'WORD_MATCH_ALPHANUMERIC' | 'PREFIX' | 'SUFFIX' | 'CONTAINS' | 'EXACT' — WORD_MATCH - using word boundaries, WORD_MATCH_ALPHANUMERIC - using word boundaries, but replaces non-alphanumeric characters in the search with a word boundary match, PREFIX - same case prefix, SUFFIX - same case suffix, CONTAINS - same case contains EXACT - same case exact - `orSortCode.value` string - `orAccountNumber.type` 'WORD_MATCH' | 'WORD_MATCH_ALPHANUMERIC' | 'PREFIX' | 'SUFFIX' | 'CONTAINS' | 'EXACT' — WORD_MATCH - using word boundaries, WORD_MATCH_ALPHANUMERIC - using word boundaries, but replaces non-alphanumeric characters in the search with a word boundary match, PREFIX - same case prefix, SUFFIX - same case suffix, CONTAINS - same case contains EXACT - same case exact - `orAccountNumber.value` string - `orIban.type` 'WORD_MATCH' | 'WORD_MATCH_ALPHANUMERIC' | 'PREFIX' | 'SUFFIX' | 'CONTAINS' | 'EXACT' — WORD_MATCH - using word boundaries, WORD_MATCH_ALPHANUMERIC - using word boundaries, but replaces non-alphanumeric characters in the search with a word boundary match, PREFIX - same case prefix, SUFFIX - same case suffix, CONTAINS - same case contains EXACT - same case exact - `orIban.value` string - `orAbaRoutingNumber.type` 'WORD_MATCH' | 'WORD_MATCH_ALPHANUMERIC' | 'PREFIX' | 'SUFFIX' | 'CONTAINS' | 'EXACT' — WORD_MATCH - using word boundaries, WORD_MATCH_ALPHANUMERIC - using word boundaries, but replaces non-alphanumeric characters in the search with a word boundary match, PREFIX - same case prefix, SUFFIX - same case suffix, CONTAINS - same case contains EXACT - same case exact - `orAbaRoutingNumber.value` string - `orName.type` 'WORD_MATCH' | 'WORD_MATCH_ALPHANUMERIC' | 'PREFIX' | 'SUFFIX' | 'CONTAINS' | 'EXACT' — WORD_MATCH - using word boundaries, WORD_MATCH_ALPHANUMERIC - using word boundaries, but replaces non-alphanumeric characters in the search with a word boundary match, PREFIX - same case prefix, SUFFIX - same case suffix, CONTAINS - same case contains EXACT - same case exact - `orName.value` string - `orExternalReference.type` 'WORD_MATCH' | 'WORD_MATCH_ALPHANUMERIC' | 'PREFIX' | 'SUFFIX' | 'CONTAINS' | 'EXACT' — WORD_MATCH - using word boundaries, WORD_MATCH_ALPHANUMERIC - using word boundaries, but replaces non-alphanumeric characters in the search with a word boundary match, PREFIX - same case prefix, SUFFIX - same case suffix, CONTAINS - same case contains EXACT - same case exact - `orExternalReference.value` string - `orDefaultReference.type` 'WORD_MATCH' | 'WORD_MATCH_ALPHANUMERIC' | 'PREFIX' | 'SUFFIX' | 'CONTAINS' | 'EXACT' — WORD_MATCH - using word boundaries, WORD_MATCH_ALPHANUMERIC - using word boundaries, but replaces non-alphanumeric characters in the search with a word boundary match, PREFIX - same case prefix, SUFFIX - same case suffix, CONTAINS - same case contains EXACT - same case exact - `orDefaultReference.value` string - `createdDate` string, date — Created date - `partialName` string — Partial name - `sortCode` string — Sort code - `accountNumber` string — Account number - `page` integer — Page to fetch (0 indexed) - `size` integer — Size of Page to fetch ## Response `200` OK - AccountBeneficiaryPageResponse - `content` AccountBeneficiaryResponse[] — List of responses on the current page - `id` string — Unique reference for the Beneficiary. - `name` string — Name for the Beneficiary - `birthdate` string, date — Date of birth for the Beneficiary in yyyy-MM-dd format - `emailAddress` string — Email address for the Beneficiary - `phoneNumber` string — Phone number for the Beneficiary in international pattern - `destinationIdentifier` AccountIdentifierResponse — Account Identifier - `type` string - `accountNumber` string — Bank account Sort Code - `accountType` 'PERSONAL' | 'BUSINESS' — Bank account type like PERSONAL/BUSINESS - `sortCode` string — Bank account Sort Code - `iban` string - `bic` string - `currency` string - `countrySpecificDetails` AccountIdentifierCountrySpecificDetailsResponse - `bankName` string — The name of the destination bank. - `bankAddress` string — The address of the destination bank. - `bankCity` string — The city in which the destination bank resides. - `bankBranchName` string — The name of the destination bank's branch. - `bankBranchCode` string — The code of the destination bank's branch. - `bankCode` string — The code identifying the target bank on its respective national network. This is not the BIC/SWIFT code. This is known as the 'ABA code' in the U.S., 'ISFC' in India, 'routing number' in Canada, and so on. - `chineseId` string — The 18 digit identification code of the beneficiary. Applies to Chinese beneficiaries only. - `province` string — The province in which the beneficiary resides. Applies only to beneficiaries residing in China. - `business` boolean — The type of the beneficiary. 'true' for businesses, 'false' otherwise. - `bankCodeType` 'ABA' | 'CHIPS' — The code type identifying the target bank on its respective national network. This is known as the 'ABA code' in the U.S., 'ISFC' in India, 'routing number' in Canada, and so on. - `bankCountry` 'AT' | 'BE' | 'BG' | 'CY' | 'CZ' | 'DK' | 'EE' | 'FI' | 'FR' | 'DE' | 'GR' | 'HR' | 'HU' | 'IS' | 'IE' | 'IT' | 'LV' | 'LI' | 'LT' | 'LU' | 'MT' | 'NL' | 'NO' | 'PL' | 'PT' | 'RO' | 'SK' | 'SI' | 'ES' | 'SE' | 'GB' | 'MQ' | 'YT' | 'GP' | 'GF' | 'RE' | 'MF' | 'GI' | 'GG' | 'IM' | 'JE' | 'MC' | 'CH' | 'AD' | 'SM' | 'VA' | 'AX' | 'PM' | 'BL' | 'AL' | 'MD' | 'ME' | 'MK' | 'RS' | 'AF' | 'DZ' | 'AS' | 'AO' | 'AI' | 'AQ' | 'AG' | 'AR' | 'AM' | 'AW' | 'AU' | 'AZ' | 'BS' | 'BH' | 'BD' | 'BB' | 'BY' | 'BZ' | 'BJ' | 'BM' | 'BT' | 'BO' | 'BQ' | 'BA' | 'BW' | 'BV' | 'BR' | 'IO' | 'VG' | 'BN' | 'BF' | 'BI' | 'KH' | 'CM' | 'CA' | 'CV' | 'KY' | 'CF' | 'TD' | 'CL' | 'CN' | 'CX' | 'CC' | 'CO' | 'KM' | 'CK' | 'CR' | 'CU' | 'CW' | 'CD' | 'DJ' | 'DM' | 'DO' | 'TL' | 'EC' | 'EG' | 'SV' | 'GQ' | 'ER' | 'SZ' | 'ET' | 'FK' | 'FO' | 'FJ' | 'PF' | 'TF' | 'GA' | 'GM' | 'GE' | 'GH' | 'GL' | 'GD' | 'GU' | 'GT' | 'GN' | 'GW' | 'GY' | 'HT' | 'HM' | 'HN' | 'HK' | 'IN' | 'ID' | 'IR' | 'IQ' | 'IL' | 'CI' | 'JM' | 'JP' | 'JO' | 'KZ' | 'KE' | 'KI' | 'XK' | 'KW' | 'KG' | 'LA' | 'LB' | 'LS' | 'LR' | 'LY' | 'MO' | 'MG' | 'MW' | 'MY' | 'MV' | 'ML' | 'MH' | 'MR' | 'MU' | 'MX' | 'FM' | 'MN' | 'MS' | 'MA' | 'MZ' | 'MM' | 'NA' | 'NR' | 'NP' | 'AN' | 'NC' | 'NZ' | 'NI' | 'NE' | 'NG' | 'NU' | 'NF' | 'KP' | 'MP' | 'OM' | 'PK' | 'PW' | 'PS' | 'PA' | 'PG' | 'PY' | 'PE' | 'PH' | 'PN' | 'PR' | 'QA' | 'CG' | 'RU' | 'RW' | 'SH' | 'KN' | 'LC' | 'VC' | 'WS' | 'ST' | 'SA' | 'SN' | 'SC' | 'SL' | 'SG' | 'SX' | 'SB' | 'SO' | 'ZA' | 'KR' | 'GS' | 'SS' | 'LK' | 'SD' | 'SR' | 'SY' | 'SJ' | 'TW' | 'TJ' | 'TZ' | 'TH' | 'TG' | 'TK' | 'TO' | 'TT' | 'TN' | 'TR' | 'TM' | 'TC' | 'TV' | 'UG' | 'UA' | 'AE' | 'UM' | 'US' | 'UY' | 'UZ' | 'VU' | 'VE' | 'VN' | 'VI' | 'WF' | 'EH' | 'YE' | 'ZM' | 'ZW' — The country in which the destination bank resides. - `abaRoutingNumber` string — The 9 digit identification code of the beneficiary. Applies to US beneficiaries only. - `productId` string - `redirectedDestination` AccountIdentifierResponse — Account Identifier - `type` string - `accountNumber` string — Bank account Sort Code - `accountType` 'PERSONAL' | 'BUSINESS' — Bank account type like PERSONAL/BUSINESS - `sortCode` string — Bank account Sort Code - `iban` string - `bic` string - `currency` string - `countrySpecificDetails` AccountIdentifierCountrySpecificDetailsResponse - `bankName` string — The name of the destination bank. - `bankAddress` string — The address of the destination bank. - `bankCity` string — The city in which the destination bank resides. - `bankBranchName` string — The name of the destination bank's branch. - `bankBranchCode` string — The code of the destination bank's branch. - `bankCode` string — The code identifying the target bank on its respective national network. This is not the BIC/SWIFT code. This is known as the 'ABA code' in the U.S., 'ISFC' in India, 'routing number' in Canada, and so on. - `chineseId` string — The 18 digit identification code of the beneficiary. Applies to Chinese beneficiaries only. - `province` string — The province in which the beneficiary resides. Applies only to beneficiaries residing in China. - `business` boolean — The type of the beneficiary. 'true' for businesses, 'false' otherwise. - `bankCodeType` 'ABA' | 'CHIPS' — The code type identifying the target bank on its respective national network. This is known as the 'ABA code' in the U.S., 'ISFC' in India, 'routing number' in Canada, and so on. - `bankCountry` 'AT' | 'BE' | 'BG' | 'CY' | 'CZ' | 'DK' | 'EE' | 'FI' | 'FR' | 'DE' | 'GR' | 'HR' | 'HU' | 'IS' | 'IE' | 'IT' | 'LV' | 'LI' | 'LT' | 'LU' | 'MT' | 'NL' | 'NO' | 'PL' | 'PT' | 'RO' | 'SK' | 'SI' | 'ES' | 'SE' | 'GB' | 'MQ' | 'YT' | 'GP' | 'GF' | 'RE' | 'MF' | 'GI' | 'GG' | 'IM' | 'JE' | 'MC' | 'CH' | 'AD' | 'SM' | 'VA' | 'AX' | 'PM' | 'BL' | 'AL' | 'MD' | 'ME' | 'MK' | 'RS' | 'AF' | 'DZ' | 'AS' | 'AO' | 'AI' | 'AQ' | 'AG' | 'AR' | 'AM' | 'AW' | 'AU' | 'AZ' | 'BS' | 'BH' | 'BD' | 'BB' | 'BY' | 'BZ' | 'BJ' | 'BM' | 'BT' | 'BO' | 'BQ' | 'BA' | 'BW' | 'BV' | 'BR' | 'IO' | 'VG' | 'BN' | 'BF' | 'BI' | 'KH' | 'CM' | 'CA' | 'CV' | 'KY' | 'CF' | 'TD' | 'CL' | 'CN' | 'CX' | 'CC' | 'CO' | 'KM' | 'CK' | 'CR' | 'CU' | 'CW' | 'CD' | 'DJ' | 'DM' | 'DO' | 'TL' | 'EC' | 'EG' | 'SV' | 'GQ' | 'ER' | 'SZ' | 'ET' | 'FK' | 'FO' | 'FJ' | 'PF' | 'TF' | 'GA' | 'GM' | 'GE' | 'GH' | 'GL' | 'GD' | 'GU' | 'GT' | 'GN' | 'GW' | 'GY' | 'HT' | 'HM' | 'HN' | 'HK' | 'IN' | 'ID' | 'IR' | 'IQ' | 'IL' | 'CI' | 'JM' | 'JP' | 'JO' | 'KZ' | 'KE' | 'KI' | 'XK' | 'KW' | 'KG' | 'LA' | 'LB' | 'LS' | 'LR' | 'LY' | 'MO' | 'MG' | 'MW' | 'MY' | 'MV' | 'ML' | 'MH' | 'MR' | 'MU' | 'MX' | 'FM' | 'MN' | 'MS' | 'MA' | 'MZ' | 'MM' | 'NA' | 'NR' | 'NP' | 'AN' | 'NC' | 'NZ' | 'NI' | 'NE' | 'NG' | 'NU' | 'NF' | 'KP' | 'MP' | 'OM' | 'PK' | 'PW' | 'PS' | 'PA' | 'PG' | 'PY' | 'PE' | 'PH' | 'PN' | 'PR' | 'QA' | 'CG' | 'RU' | 'RW' | 'SH' | 'KN' | 'LC' | 'VC' | 'WS' | 'ST' | 'SA' | 'SN' | 'SC' | 'SL' | 'SG' | 'SX' | 'SB' | 'SO' | 'ZA' | 'KR' | 'GS' | 'SS' | 'LK' | 'SD' | 'SR' | 'SY' | 'SJ' | 'TW' | 'TJ' | 'TZ' | 'TH' | 'TG' | 'TK' | 'TO' | 'TT' | 'TN' | 'TR' | 'TM' | 'TC' | 'TV' | 'UG' | 'UA' | 'AE' | 'UM' | 'US' | 'UY' | 'UZ' | 'VU' | 'VE' | 'VN' | 'VI' | 'WF' | 'EH' | 'YE' | 'ZM' | 'ZW' — The country in which the destination bank resides. - `abaRoutingNumber` string — The 9 digit identification code of the beneficiary. Applies to US beneficiaries only. - `productId` string - `defaultReference` string — Default reference used for payments to the Beneficiary. - `status` string — Status of the Beneficiary. Can be: - `created` string, date-time — Datetime the Beneficiary was created.Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000 - `accountId` string — Id of the account if this beneficiary is a Modulr account, null otherwise - `externalReference` string — External system reference for the Beneficiary - `approvalRequired` boolean — Indicates if the beneficiary creation is pending approval - `customerId` string — Id of the customer than owns this beneficiary - `updated` string, date-time — Datetime the Beneficiary was last updated.Format is 'yyyy-MM-dd'T'HH:mm:ssZ' where Z is UTC offset. e.g 2017-01-28T01:01:01+0000 - `address` AccountAddressResponse — Address - `addressLine1` string - `addressLine2` string - `postTown` string - `postCode` string - `country` string - `countrySubDivision` string - `qualifier` string — Qualifier for this beneficiary - `approvalRequestId` string — Approval request ID for pending records. - `approvalStatus` 'NOTNEEDED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'DELETED' — Approval status of item. - `accessGroups` string[] — Access groups associated with beneficiary. - `createdBy` string — System or person who created the beneficiary - `size` integer — Page size - `totalSize` integer — Total count - `page` integer — Current page number, 0 based; i.e first-page = 0, second-page = 1 - `totalPages` integer — Total pages ## Other responses - `400` — Bad Request --- [API](https://skmtc.net/modulrfinance/apis/modulr-api.md) · [All operations](https://skmtc.net/modulrfinance/apis/modulr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/modulrfinance/modulr-api/revisions/cbd52524c8ef/schema)