Creates a new conversion, and upon success, returns the details of the created conversion.

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.
buy_currency formData string Currency purchased. Three-digit code.
sell_currency formData string Currency sold. Three-digit code.
fixed_side formData string Fix the buy or sell currency. buy
amount formData string Amount of the fixed buy or sell currency.
term_agreement formData boolean Indicates agreement to terms and conditions.
conversion_date formData string Earliest delivery date in UTC time zone. Format YYYY-MM-DD. date
client_buy_amount formData string Client buy amount.
client_sell_amount formData string Client sell amount.
reason formData string User-generated reason for payment. Freeform text.
unique_request_id formData string User-generated idempotency key. Beneficial for request tracking / management.
on_behalf_of formData string A contact UUID for the sub-acccount you're acting on behalf of.
conversion_date_preference formData string Available and required only if conversion_date is not provided. Not currently supported for APAC currencies.
Must be one of the following:
- 'earliest' for earliest available conversion date. Make sure there is sufficient time to send funds to Currencycloud.
- 'next_day' for next day available conversion date - T+1.
- 'default' for conversion - T+1 for APAC, T+2 for everywhere else.
- 'optimize_liquidity' for maximizing chances of getting a successful rate. Most relevant for exotic pairs. Conversion is within 1 or 2 working days depending on currencies.
curl -X POST  --header "X-Auth-Token: XXXX-XXXXX-XXXX"  https://devapi.currencycloud.com/v2/conversions/create


    "id": "1873a622-ce56-4357-a016-84b850aca99f",
    "settlement_date": "2022-02-02T16:30:00+00:00",
    "conversion_date": "2022-02-02T00:00:00+00:00",
    "short_reference": "20220131-BHWNYW",
    "creator_contact_id": "a66ca63f-e668-47af-8bb9-74363240d781",
    "account_id": "72970a7c-7921-431c-b95f-3438724ba16f",
    "currency_pair": "GBPUSD",
    "status": "awaiting_funds",
    "buy_currency": "USD",
    "sell_currency": "GBP",
    "client_buy_amount": "150.00",
    "client_sell_amount": "106.54",
    "fixed_side": "buy",
    "core_rate": "1.4079",
    "partner_rate": "",
    "partner_buy_amount": "0.00",
    "partner_sell_amount": "0.00",
    "client_rate": "1.4079",
    "deposit_required": false,
    "deposit_amount": "0.00",
    "deposit_currency": "",
    "deposit_status": "not_required",
    "deposit_required_at": "",
    "payment_ids": [],
    "unallocated_funds": "150.00",
    "unique_request_id": null,
    "created_at": "2022-01-31T14:30:39+00:00",
    "updated_at": "2022-01-31T14:30:40+00:00",
    "mid_market_rate": "1.4080"
Error Codes
HTTP Status Code Description Params
400 invalid_extra_parameters Invalid extra parameters { "parameters" => { "extra_param" => "extra_value" } }
buy_currency_is_in_invalid_format buy_currency is not a valid ISO 4217 currency code { "type" => "currency" }
buy_currency_is_required buy_currency is required
invalid_buy_currency buy_currency is invalid
sell_currency_is_required sell_currency is required
sell_currency_is_in_invalid_format sell_currency is not a valid ISO 4217 currency code { "type" => "currency" }
invalid_sell_currency sell_currency is invalid
amount_is_required amount is required
conversion_above_limit Conversion of GBP equivalent 30000.01 exceeds your limit of 30000.00 { "amount" => "30000.01", "limit_amount" => "30000.00", "ccy" => "GBP" }
conversion_below_limit Conversion of GBP equivalent 999.99 is less than your lower limit of 1000.00 { "amount" => "999.99", "limit_amount" => "1000.00", "ccy" => "GBP" }
amount_type_is_wrong amount should be of numeric type { "type" => "numeric" }
reason_is_required reason is required
reason_is_too_short reason can not be shorter than 1 character(s) { "minlength" => 1 }
client_rate_is_in_invalid_format client_rate should be of numeric type with 4 dp { "type" => "numeric_with_precision", "precision" => 4 }
invalid_client_rate client_rate is invalid { "client_rate" => "1.455543..1.778997" }
currency_pair_not_available_for_weekend Currency pair is not available for weekend
client_rate_is_required The client_rate is required if you supply currency_pair
fixed_side_is_required fixed_side is required
fixed_side_not_in_range fixed_side should be in range: buy, sell { "range" => "buy, sell" }
term_agreement_is_required term_agreement is required
term_agreement_type_is_wrong term_agreement should be of boolean type { "type" => "boolean" }
conversion_create_failed Conversion create failed
currency_pair_is_in_invalid_format currency_pair is not a valid ISO 4217 currency code { "type" => "currency_pair" }
invalid_currency_pair The currency_pair should be the real market pair of the buy_currency and sell_currency
on_behalf_of_self You cannot act on behalf of your own Contact
contact_not_found Contact was not found for this id
on_behalf_of_is_not_valid_uuid on_behalf_of should be in UUID format
on_behalf_of_is_required You should do this conversion on behalf of someone if you supply client_rate
currency_pair_is_required The currency_pair is required if you supply client_rate
variable_value_dates_not_permitted Sorry - you are not currently setup to trade with variable value dates, please contact us on the phone if you want to change this or wish to trade now on the phone.
client_buy_amount_is_in_invalid_format client_buy_amount should be of numeric type with 2 dp { "type" => "client_buy_amount" }
client_sell_amount_is_in_invalid_format client_sell_amount should be of numeric type with 2 dp { "type" => "client_sell_amount" }
cannot_fix_client_sell_on_fixed_sell_side You cannot specify a fixed client_sell_amount when the fixed side for a conversion is the sell side { "type" => "client_sell_amount" }
client_buy_amount_exceeds_partner_buy_amount The client buy amount specified is greater than the amount that you would be buying and is thus invalid { "type" => "client_buy_amount" }
partner_sell_amount_exceeds_client_sell_amount The client sell amount specified is less than the amount that you would be selling and is thus invalid { "type" => "client_sell_amount" }
missing_partner_spread_table_data Sorry, the online partner pricing for the amount of the currency pair you are trying to trade has not been set up
missing_client_spread_table_data Sorry, the online client pricing for the amount of the currency pair you are trying to trade has not been set up
fixed_amounts_not_permitted_for_this_user You are not permitted to specify a fixed client_buy_amount or client_sell_amount for this customer
invalid_client_rate_combination You cannot specify a client rate and client currency pair alongside a client buy amount or client sell amount
duplicate_request The unique_request_id provided for this conversion has already been used, please provide a new unique_request_id to successfully submit this conversion
invalid_conversion_date_combination conversion_date_preference can not be specified along side a date parameter
invalid_conversion_date_preference not a valid conversion date preference, possible options are earliest, optimize_liquidity, default, next_day
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.