Sign in

v1

latestOpenAPI 3.1.0© Modulr Finance2026-08-04207430590.4 KB
Beneficiaries

Retrieve 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.

get/beneficiaries

Query parameters

idstring[]

ID of Customer(s) to fetch

Id of Beneficiary(s) to fetch

customerIdstring

Filter by Customer Id

Filter by Customer Id

qstring

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

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

modifiedSincestring

Beneficiaries modified after this date time

Beneficiaries modified after this date time

hasExternalReferenceboolean

Filter by existence of external reference

Filter by existence of external reference

externalReferencestring

External reference for beneficiary

External reference for beneficiary

ibanstring

IBAN

IBAN

abaRoutingNumberstring

abaRoutingNumber

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

Currency

qualifierstring[]

A list of external qualifiers

A list of external qualifiers

statestring[]

Approval item state(s) to filter by

Approval item state(s) to filter by

validForAccountstring

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

Example:A000000001

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

sortOrderstring

Sort order

Sort order

sortFieldstring

Sort by field, This defaults to name if not present

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

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.valuestring
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

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.valuestring
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

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.valuestring
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

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.valuestring
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

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.valuestring
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

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.valuestring
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

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.valuestring
createdDatestring date

Created date

Created date

partialNamestring

Partial name

Partial name

sortCodestring

Sort code

Sort code

accountNumberstring

Account number

Account number

pageinteger

Page to fetch (0 indexed)

Page to fetch (0 indexed)

sizeinteger

Size of Page to fetch

Size of Page to fetch

Response

OK

sizeinteger

Page size

totalSizeinteger

Total count

pageinteger

Current page number, 0 based; i.e first-page = 0, second-page = 1

totalPagesinteger

Total pages

Example response

{
  "content": [
    {
      "id": "B00000001A",
      "destinationIdentifier": {
        "accountNumber": "12345678",
        "sortCode": "000000",
        "iban": "GB20MODR04001401100000",
        "bic": "MODRGB21",
        "currency": "GBP",
        "countrySpecificDetails": {
          "bankName": "Apple Bank",
          "bankAddress": "2100 Broadway",
          "bankCity": "New York City",
          "bankBranchName": "New York",
          "bankBranchCode": "44-04",
          "chineseId": "01101201901018889",
          "province": "Zhejiang",
          "business": true,
          "bankCodeType": "ABA",
          "bankCountry": "US",
          "abaRoutingNumber": "123456789"
        },
        "productId": "O2100001"
      },
      "redirectedDestination": {
        "accountNumber": "12345678",
        "sortCode": "000000",
        "iban": "GB20MODR04001401100000",
        "bic": "MODRGB21",
        "currency": "GBP",
        "countrySpecificDetails": {
          "bankName": "Apple Bank",
          "bankAddress": "2100 Broadway",
          "bankCity": "New York City",
          "bankBranchName": "New York",
          "bankBranchCode": "44-04",
          "chineseId": "01101201901018889",
          "province": "Zhejiang",
          "business": true,
          "bankCodeType": "ABA",
          "bankCountry": "US",
          "abaRoutingNumber": "123456789"
        },
        "productId": "O2100001"
      },
      "created": "2017-01-28T01:01:01+0000",
      "customerId": "C0000001",
      "updated": "2017-01-28T01:01:01+0000"
    }
  ]
}