v1

latestOpenAPI 3.1.0© Modulr Finance2026-08-04207430590.4 KB

Beneficiaries

Create a new beneficiary for a specified customer

The ability to create a new beneficiary for a customer, using their customer ID as a reference.

post/customers/{customerId}/beneficiaries

Path parameters

customerIdstring required

ID of customer to create beneficiary for

Request body

externalReferencestring

External Reference can only have alphanumeric characters plus underscore, hyphen and space up to 50 characters long

namestring required

birthdatestring date

The destination beneficiary's date of birth. Date in yyyy-MM-dd format

emailAddressstring email

The destination beneficiary's email address

phoneNumberstring

The destination beneficiary's phone number, will be formatted into international number pattern

defaultReferencestring required

idToReplacestring

qualifierstring

Optional qualifier. Only to be supplied if multiple beneficiaries with same destination need to be supplied

Example request

{
  "destinationIdentifier": {
    "accountNumber": "12345678",
    "sortCode": "000000",
    "iban": "GB20MODR00000000000001",
    "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"
    }
  }
}

Response

Created

idstring

Unique reference for the Beneficiary.

namestring

Name for the Beneficiary

birthdatestring date

Date of birth for the Beneficiary in yyyy-MM-dd format

emailAddressstring

Email address for the Beneficiary

phoneNumberstring

Phone number for the Beneficiary in international pattern

defaultReferencestring

Default reference used for payments to the Beneficiary.

statusstring

Status of the Beneficiary. Can be:

createdstring 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

accountIdstring

Id of the account if this beneficiary is a Modulr account, null otherwise

externalReferencestring

External system reference for the Beneficiary

approvalRequiredboolean

Indicates if the beneficiary creation is pending approval

customerIdstring

Id of the customer than owns this beneficiary

updatedstring 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

qualifierstring

Qualifier for this beneficiary

approvalRequestIdstring

Approval request ID for pending records.

approvalStatus'NOTNEEDED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'DELETED'

Approval status of item.

accessGroupsstring[]

Access groups associated with beneficiary.

createdBystring

System or person who created the beneficiary

Example response

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