Create a new sub-account. On success, returns the new account 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

X-Auth-Token header string Authentication token.
account_name formData string Account name.
legal_entity_type formData string Legal entity. company
street formData string First line of address.
city formData string City.
country formData string Two-letter country code.
postal_code formData string Postal code. Required for sub-accounts on our outsourced KYC model, also required where country = "US", "CA" or "MX".
brand formData string The value of this field is used for white labeling the Currencycloud user interface. If nothing is specified then the account will inherit the house account's brand.
your_reference formData string User-generated reference code.
status formData string Account status. enabled
state_or_province formData string State or province two-letter ISO 3166 code. Only applicable to some countries, required where country = "US", "CA" or "MX".
spread_table formData string The name of the spread table assigned to the account. This is needed if they intend to apply markup. flat_0.00
api_trading formData boolean Allows the account to make trades via the Currencycloud API.
online_trading formData boolean Allows the account to make trades via Currencycloud Direct.
phone_trading formData boolean Allows the account to make trades via phone.
identification_type formData string A legal document that verifies the identity of the account owner. Required for individual sub-accounts on our outsourced KYC model, optional otherwise. none
identification_value formData string A unique reference code for the identification document, such as a passport number. Required if "identification_type" is provided.
terms_and_conditions_accepted formData boolean Acceptance of the terms and conditions. Required for sub-accounts that are on our Outsourced KYC model, optional otherwise.
curl -X POST  --header "X-Auth-Token: XXXX-XXXXX-XXXX"  https://devapi.currencycloud.com/v2/accounts/create


    "id": "66f51c98-1ef8-4e48-97de-aac0353ba2b4",
    "account_name": "My Example Account",
    "brand": "currency_cloud_dev_centre",
    "your_reference": null,
    "status": "enabled",
    "street": "My Example Street",
    "city": "My Example City",
    "state_or_province": null,
    "country": "GB",
    "postal_code": "Example Code",
    "spread_table": "flat_0.00",
    "legal_entity_type": "company",
    "created_at": "2022-01-31T14:30:29.000Z",
    "updated_at": "2022-01-31T14:30:29.000Z",
    "identification_type": null,
    "identification_value": null,
    "short_reference": "220131-27603",
    "api_trading": true,
    "online_trading": true,
    "phone_trading": true,
    "process_third_party_funds": false,
    "settlement_type": "net",
    "agent_or_reliance": false,
    "terms_and_conditions_accepted": null,
    "bank_account_verified": "not required"
Error Codes
HTTP Status Code Description Params
400 account_name_is_too_short account_name can not be shorter than 1 character(s) { "minlength" => 1 }
account_name_is_too_long account_name can not be longer than 150 character(s) { "maxlength" => 150 }
account_name_is_required account_name is required
brand_is_too_short brand can not be shorter than 1 character(s) { "minlength" => 1 }
brand_is_too_long brand can not be longer than 100 character(s) { "maxlength" => 255 }
brand_not_found Brand non_existing_brand wasn't found { "brand" => "non_existing_brand" }
brand_account_not_broker Account doesn't have broker permissions { "brand" => "wrong_brand" }
your_reference_is_too_long your_reference can not be longer than 25 character(s) { "maxlength" => 25 }
status_not_in_range status should be in range: enabled, disabled, enabled_no_trading { "range" => "enabled, disabled, enabled_no_trading" }
legal_entity_type_not_in_range legal_entity_type should be in range: individual, company { "range" => "individual, company" }
legal_entity_type_is_required Legal entity type is required
street_is_too_long street can not be longer than 150 character(s) { "maxlength" => 150 }
street_is_required Street is required
city_is_too_long city can not be longer than 100 character(s) { "maxlength" => 100 }
city_is_required City is required
postal_code_is_too_long postal_code can not be longer than 20 character(s) { "maxlength" => 20 }
postal_code_is_required Postal code is required
state_or_province_invalid_format state or province should be a two-letter ISO 3166 code { "maxlength" => 2 }
country_is_too_long country can not be longer than 2 character(s) { "maxlength" => 2 }
country_is_required Country is required
spread_table_is_too_long spread_table can not be longer than 100 character(s) { "maxlength" => 100 }
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
state_or_province_is_required State or province is required for US, CA and MX
terms_and_conditions_accepted_is_required Terms and conditions accepted is required
invalid_extra_parameters Invalid extra parameters extra_parameter { "parameters" => "extra_parameter" }
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 post helpful?
Let us know if you liked the post. That’s the only way we can improve.