/v2/beneficiaries/create

POST

Create a new beneficiary. On success, returns the new beneficiary entity.

The API responses shown below are static. If you want to try out the API please login, or register for an API key

API parameters

Required
NameInTypeDescriptionEnumDefaultItems
X-Auth-Token header string Authentication token.
name formData string Beneficiary name.
bank_account_holder_name formData string Bank account holder's name.
bank_country formData string Two-letter code for the country in which the beneficiary's bank account is held.
currency formData string Currency in which money is held in the beneficiary's bank account. Three-digit currency code.
Optional
NameInTypeDescriptionEnumDefaultItems
email formData string Email address.
beneficiary_address formData string First line of address.
beneficiary_country formData string Two-letter country code. If the beneficiary is a company, the country in which the company is registered. If the beneficiary is an individual, a country in which the beneficiary holds nationality.
account_number formData string Bank account number.
routing_code_type_1 formData string Local payment routing system. sort_code
aba
bsb_code
institution_no
bank_code
branch_code
clabe
cnaps
ifsc
routing_code_value_1 formData string Routing code for "routing_code_type_1".
routing_code_type_2 formData string Local payment routing system. sort_code
aba
bsb_code
institution_no
bank_code
branch_code
clabe
cnaps
routing_code_value_2 formData string Routing code for "routing_code_type_2".
bic_swift formData string BIC/SWIFT code.
iban formData string IBAN code.
default_beneficiary formData boolean Payments are made automatically to default beneficiaries when a beneficiary is not specified.
bank_address formData string First line of address.
bank_name formData string Bank name.
bank_account_type formData string Bank account type. checkings
savings
beneficiary_entity_type formData string Legal entity. individual
company
beneficiary_company_name formData string Required if "beneficiary_entity_type" is "company".
beneficiary_first_name formData string Required if "beneficiary_entity_type" is "individual".
beneficiary_last_name formData string Required if "beneficiary_entity_type" is "individual".
beneficiary_city formData string City.
beneficiary_postcode formData string Postal code.
beneficiary_state_or_province formData string State or province.
beneficiary_date_of_birth formData string If "beneficiary_entity_type" is "company", date of registration. If "beneficiary_entity_type" is "individual", date of birth. ISO 8601 format YYYY-MM-DD.
beneficiary_identification_type formData string A legal document that verifies the identity of the beneficiary. Required documentation will vary depending on the country in which the beneficiary's bank account is held.
beneficiary_identification_value formData string A unique reference code for the identification document, such as a passport number. none
drivers_license
social_security_number
green_card
passport
visa
matricula_consular
registro_federal_de_contribuyentes
clave_unica_de_registro_de_poblacion
credential_de_elector
social_insurance_number
citizenship_papers
drivers_license_canadian
existing_credit_card_details
employer_identification_number
national_id
incorporation_number
others
payment_types[] formData array Currencycloud supports two types of payments: "priority", made using the SWIFT network; and "regular", made using the local bank network. regular
string
Array
on_behalf_of formData string Contact UUID.
curl -X POST  --header "X-Auth-Token: XXXX-XXXXX-XXXX"  https://devapi.currencycloud.com/v2/beneficiaries/create

Response

{
    "id": "6a1749c6-2632-45eb-aed3-9e7d438a632b",
    "bank_account_holder_name": "My Test Account Holder",
    "name": "My Test Beneficiary 5bc716274ad4d",
    "email": null,
    "payment_types": [
        "regular"
    ],
    "beneficiary_address": [],
    "beneficiary_country": null,
    "beneficiary_entity_type": null,
    "beneficiary_company_name": null,
    "beneficiary_first_name": null,
    "beneficiary_last_name": null,
    "beneficiary_city": null,
    "beneficiary_postcode": null,
    "beneficiary_state_or_province": null,
    "beneficiary_date_of_birth": null,
    "beneficiary_identification_type": null,
    "beneficiary_identification_value": null,
    "bank_country": "GB",
    "bank_name": "TEST BANK NAME",
    "bank_account_type": null,
    "currency": "GBP",
    "account_number": "3284734675",
    "routing_code_type_1": "sort_code",
    "routing_code_value_1": "101193",
    "routing_code_type_2": null,
    "routing_code_value_2": null,
    "bic_swift": null,
    "iban": null,
    "default_beneficiary": "false",
    "creator_contact_id": "a66ca63f-e668-47af-8bb9-74363240d781",
    "bank_address": [
        "TEST BANK ADDRESS",
        " NOT USING EXTERNAL SERVICE",
        " DEVELOPMENT ENVIRONMENT."
    ],
    "created_at": "2018-10-17T11:00:13+00:00",
    "updated_at": "2018-10-17T11:00:13+00:00",
    "beneficiary_external_reference": null
}
Error Codes
HTTP Status Code Description Params
400 bank_account_holder_name_is_required bank_account_holder_name is required
bank_account_holder_name_is_too_short bank_account_holder_name can not be shorter than 1 character(s) { "minlength" => 1 }
bank_account_holder_name_is_too_long bank_account_holder_name can not be longer than 255 character(s) { "maxlength" => 255 }
email_is_too_short email can not be shorter than 1 character(s) { "minlength" => 1 }
email_is_too_long email can not be longer than 255 character(s) { "maxlength" => 255 }
beneficiary_address_is_too_short beneficiary_address can not be shorter than 1 character(s) { "minlength" => 1 }
beneficiary_address_is_too_long beneficiary_address can not be longer than 255 character(s) { "maxlength" => 255 }
beneficiary_address_is_missing Beneficiary address is missing
account_number_is_too_short account_number can not be shorter than 1 character(s) { "minlength" => 1 }
account_number_is_too_long account_number can not be longer than 50 character(s) { "maxlength" => 50 }
account_number_is_missing Account number is missing
account_number_is_invalid Account number is in invalid format
routing_code_value_1_is_too_short routing_code_value_1 can not be shorter than 1 character(s) { "minlength" => 1 }
routing_code_value_1_is_too_long routing_code_value_1 can not be longer than 50 character(s) { "maxlength" => 50 }
routing_code_value_2_is_too_short routing_code_value_2 can not be shorter than 1 character(s) { "minlength" => 1 }
routing_code_value_2_is_too_long routing_code_value_2 can not be longer than 50 character(s) { "maxlength" => 50 }
iban_is_too_short iban can not be shorter than 1 character(s) { "minlength" => 1 }
iban_is_too_long iban can not be longer than 34 character(s) { "maxlength" => 34 }
iban_is_missing IBAN is missing
iban_is_invalid IBAN is in invalid format
bic_swift_is_too_short bic_swift can not be shorter than 1 character(s) { "minlength" => 1 }
bic_swift_is_too_long bic_swift can not be longer than 11 character(s) { "maxlength" => 11 }
bic_swift_is_missing BIC/SWIFT is missing
bic_swift_is_invalid BIC/SWIFT is in invalid format
bank_address_is_missing Bank address is missing
bank_address_is_too_short bank_address can not be shorter than 1 character(s) { "minlength" => 1 }
bank_address_is_too_long bank_address can not be longer than 100 character(s) { "maxlength" => 100 }
bank_name_is_too_short bank_name can not be shorter than 1 character(s) { "minlength" => 1 }
bank_name_is_too_long bank_name can not be longer than 100 character(s) { "maxlength" => 100 }
bank_name_is_missing Bank name is missing
bank_name_is_invalid Bank name is in invalid format
bank_account_type_not_in_range bank_account_type should be in range: checking, savings { "range" => "checking, savings" }
bank_account_type_is_missing Beneficiary bank account type is missing
name_is_too_short name can not be shorter than 1 character(s) { "minlength" => 1 }
name_is_too_long name can not be longer than 100 character(s) { "maxlength" => 100 }
default_beneficiary_type_is_wrong default_beneficiary should be of boolean type { "type" => "boolean" }
routing_code_type_1_not_in_range routing_code_type_1 should be in range: sort_code, bsb_code, institution_no, bank_code, branch_code, aba, clabe, cnaps { "range" => "sort_code, bsb_code, institution_no, bank_code, branch_code, aba, clabe, cnaps" }
routing_code_type_2_not_in_range routing_code_type_2 should be in range: sort_code, bsb_code, institution_no, bank_code, branch_code, aba, clabe, cnaps { "range => "sort_code, bsb_code, institution_no, bank_code, branch_code, aba, clabe, cnaps" }
beneficiary_country_is_required beneficiary_country is required
beneficiary_country_is_in_invalid_format beneficiary_country is in invalid format
beneficiary_entity_type_not_in_range beneficiary_entity_type should be in range: individual, company { "range" => "individual, company" }
beneficiary_entity_type_is_missing Beneficiary entity type is missing
beneficiary_company_name_is_missing Beneficiary company name is missing
beneficiary_first_name_is_missing Beneficiary first name is missing
beneficiary_last_name_is_missing Beneficiary last name is missing
beneficiary_city_is_missing Beneficiary city is missing
beneficiary_state_or_province_is_missing Beneficiary state or province is missing
beneficiary_state_or_province_is_not_supported Beneficiary state or province is not supported
beneficiary_postcode_is_missing Beneficiary postcode is missing
beneficiary_date_of_birth_type_is_wrong beneficiary_date_of_birth should be of date type { "type" => "date" }
beneficiary_date_of_birth_is_incorrect beneficiary_date_of_birth is incorrect
beneficiary_date_of_birth_is_earlier beneficiary_date_of_birth should be later
beneficiary_date_of_birth_is_after beneficiary_date_of_birth should be earlier
identification_type_is_missing identification_type is missing
identification_type_is_invalid identification_type is invalid
identification_value_is_missing identification_value is missing
identification_value_is_invalid identification_value is invalid
bank_country_is_required bank_country is required
bank_country_is_in_invalid_format bank_country is in invalid format
bank_country_is_not_supported bank_country is not supported
currency_is_required currency is required
currency_is_in_invalid_format currency is in invalid format
currency_code_is_invalid You can not use this currency with beneficiaries
unique_value_parameters Following parameters should not have same values: routing_code_type_1, routing_code_type_2 { "parameters" => "routing_code_type_1, routing_code_type_2" }
unsupported_beneficiary_country_code Beneficiary country is not supported
beneficiary_create_failed Beneficiary was not created
beneficiary_details_are_missing Following beneficiary details are missing: beneficiary_company_name { "missing_details" => ["beneficiary_company_name"] }
payment_types_not_in_range payment_types should be in range: priority, regular { "range" => "priority, regular" }
sort_code_is_missing Sort code is missing
sort_code_is_invalid Sort code is in invalid format
aba_is_missing ABA is missing
aba_is_invalid ABA is in invalid format
bsb_code_is_missing BSB code is missing
bsb_code_is_invalid BSB code is in invalid format
branch_code_is_missing Branch code is missing
branch_code_is_invalid Branch code is in invalid format
institution_no_is_missing Institution no is missing
institution_no_is_invalid Institution no is in invalid format
bank_code_is_missing Bank code is missing
bank_code_is_invalid Bank code is in invalid format
clabe_is_missing CLABE is missing
clabe_is_invalid CLABE is in invalid format
cnaps_is_missing CNAPS number is missing
cnaps_is_invalid CNAPS number is in invalid format
on_behalf_of_self You cannot act on behalf of your own Contact
contact_not_found Contact was not found for this id
401 invalid_supplied_credentials Authentication failed with the supplied credentials
429 too_many_requests Too many requests have been made to the api. Please refer to the Developer Center for more information
500 internal_server_error Internal server error
503 service_unavailable Service is temporary unavailable
Was this page helpful?
Yes
No