--- title: "Create a new beneficiary for a specified customer" method: POST path: "/customers/{customerId}/beneficiaries" tags: ["Beneficiaries"] --- # Create a new beneficiary for a specified customer `POST /customers/{customerId}/beneficiaries` The ability to create a new beneficiary for a customer, using their customer ID as a reference. ## Path parameters - `customerId` string, required ## Request body - AccountCreateBeneficiaryRequest - `externalReference` string — External Reference can only have alphanumeric characters plus underscore, hyphen and space up to 50 characters long - `name` string, required - `birthdate` string, date — The destination beneficiary's date of birth. Date in yyyy-MM-dd format - `emailAddress` string, email — The destination beneficiary's email address - `phoneNumber` string — The destination beneficiary's phone number, will be formatted into international number pattern - `destinationIdentifier` AccountIdentifierRequest, required - `type` string - `accountNumber` string - `accountType` 'PERSONAL' | 'BUSINESS' — Bank account type like PERSONAL/BUSINESS - `sortCode` string - `iban` string - `bic` string - `currency` string - `countrySpecificDetails` AccountIdentifierCountrySpecificDetailsRequest - `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. - `defaultReference` string, required - `idToReplace` string - `address` AccountAddressRequest - `addressLine1` string - `addressLine2` string - `postTown` string - `postCode` string - `country` string — Mandatory for international payments. - `countrySubDivision` string - `qualifier` string — Optional qualifier. Only to be supplied if multiple beneficiaries with same destination need to be supplied ## Response `201` Created - AccountBeneficiaryResponse — Beneficiary - `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 ## Other responses - `400` — Validation errors --- [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)