Currencycloud Conversions API
Find, retrieve and create a live currency conversion. You can also create and manage the live conversion of funds between two currencies.
OpenAPI Specification
openapi: 3.0.3
info:
title: api-onboarding Account Usage Conversions API
version: v1
description: Find, retrieve and create a live currency conversion. You can also create and manage the live conversion of funds between two currencies.
servers:
- url: /onboarding
description: Relative URL
- url: https://api.currencycloud.com/onboarding
description: Production server (uses live data)
- url: https://devapi.currencycloud.com/onboarding
description: Dev server (uses test data)
tags:
- name: Conversions
description: Find, retrieve and create a live currency conversion. You can also create and manage the live conversion of funds between two currencies.
paths:
/conversions/create:
post:
tags:
- Conversions
x-api-group: convert
summary: Create Conversion
description: Creates a new conversion. Returns the details of the created conversion on success.
operationId: CreateConversion
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: buy_currency
in: formData
required: true
type: string
description: Three-character ISO code of the currency being purchased.
format: iso-4217
pattern: ^[A-Z]{3}$
- name: sell_currency
in: formData
required: true
type: string
description: Three-character ISO code for currency sold.
format: iso-4217
pattern: ^[A-Z]{3}$
- name: fixed_side
in: formData
required: true
type: string
enum:
- buy
- sell
description: Fix the buy or sell currency.
- name: amount
in: formData
required: true
type: string
description: Amount of the fixed buy or sell currency.
pattern: ^\d+(\.\d{1,3})?$
- name: term_agreement
in: formData
required: true
type: boolean
enum:
- true
- false
description: Indicates agreement to terms and conditions.
- name: conversion_date
in: formData
required: false
type: string
format: date
description: Earliest delivery date in UTC time zone. Format YYYY-MM-DD.
- name: client_buy_amount
in: formData
required: false
type: string
description: Client buy amount.
pattern: ^\d+(\.\d{1,2})?$
- name: client_sell_amount
in: formData
required: false
type: string
description: Client sell amount.
pattern: ^\d+(\.\d{1,2})?$
- name: reason
in: formData
required: false
type: string
description: User-generated reason for conversion - freeform text.
minLength: 1
maxLength: 255
- name: unique_request_id
in: formData
required: false
type: string
description: User-generated idempotency key. Beneficial for request tracking / management.
minLength: 1
maxLength: 255
- name: on_behalf_of
in: formData
required: false
type: string
description: A contact UUID for the sub-account you're acting on behalf of.
format: uuid
- name: conversion_date_preference
in: formData
required: false
type: string
enum:
- default
- earliest
- next_day
- optimize_liquidity
description: Available and required only if conversion_date is not provided.<br> Must be one of the following:<br> - 'earliest' for earliest available conversion date. Make sure there is sufficient time to send funds to Currencycloud.<br> - 'next_day' for next day available conversion date - T+1.<br> - 'default' for conversion - T+1 for <a href="https://support.currencycloud.com/hc/en-gb/articles/360017419080-Making-payments-to-India-Indonesia-Malaysia-and-the-Philippines-INR-IDR-MYR-PHP-FAQ">APAC restricted currencies</a>, T+2 for all others.<br> - 'optimize_liquidity' for maximizing chances of getting a successful rate. Most relevant for exotic pairs. Conversion is T+0 for <a href="https://support.currencycloud.com/hc/en-gb/articles/360017419080-Making-payments-to-India-Indonesia-Malaysia-and-the-Philippines-INR-IDR-MYR-PHP-FAQ">APAC restricted currencies</a>, and T+1 or T+2 for all others.
- name: quote_id
in: formData
required: false
type: string
description: The UUID of a previously created conversion quote.
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/Conversion'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'400':
description: Client error.
x-errors:
- code: invalid_extra_parameters
category: base
message: Invalid extra parameters
params: '{ "parameters" => { "extra_param" => "extra_value" } }'
- code: buy_currency_is_in_invalid_format
category: buy_currency
message: buy_currency is not a valid ISO 4217 currency code
params: '{ "type" => "currency" }'
- code: buy_currency_is_required
category: buy_currency
message: buy_currency is required
params: ''
- code: invalid_buy_currency
category: buy_currency
message: buy_currency is invalid
params: ''
- code: sell_currency_is_required
category: sell_currency
message: sell_currency is required
params: ''
- code: sell_currency_is_in_invalid_format
category: sell_currency
message: sell_currency is not a valid ISO 4217 currency code
params: '{ "type" => "currency" }'
- code: invalid_sell_currency
category: sell_currency
message: sell_currency is invalid
params: ''
- code: amount_is_required
category: amount
message: amount is required
params: ''
- code: conversion_above_limit
category: amount
message: Conversion of ${currency} equivalent ${amount} exceeds your limit of ${limit_amount}
- code: conversion_below_limit
category: amount
message: Conversion of ${currency} equivalent ${amount} is less than your lower limit of ${limit_amount}
- code: amount_type_is_wrong
category: amount
message: amount should be of numeric type
params: '{ "type" => "numeric" }'
- code: reason_is_required
category: reason
message: reason is required
params: ''
- code: reason_is_too_short
category: reason
message: reason can not be shorter than 1 character(s)
params: '{ "minlength" => 1 }'
- code: client_rate_is_in_invalid_format
category: client_rate
message: client_rate should be of numeric type with 4 dp
params: '{ "type" => "numeric_with_precision", "precision" => 4 }'
- code: invalid_client_rate
category: client_rate
message: client_rate is invalid
params: '{ "client_rate" => "1.455543..1.778997" }'
- code: currency_pair_not_available_for_weekend
category: currency_pair_not_available_for_weekend
message: Currency pair is not available for weekend
params: ''
- code: client_rate_is_required
category: client_rate
message: The client_rate is required if you supply currency_pair
params: ''
- code: fixed_side_is_required
category: fixed_side
message: fixed_side is required
params: ''
- code: fixed_side_not_in_range
category: fixed_side
message: 'fixed_side should be in range: buy, sell'
params: '{ "range" => "buy, sell" }'
- code: term_agreement_is_required
category: term_agreement
message: term_agreement is required
params: ''
- code: term_agreement_type_is_wrong
category: term_agreement
message: term_agreement should be of boolean type
params: '{ "type" => "boolean" }'
- code: conversion_create_failed
category: conversion_create_failed
message: Conversion create failed
params: ''
- code: currency_pair_is_in_invalid_format
category: currency_pair
message: currency_pair is not a valid ISO 4217 currency code
params: '{ "type" => "currency_pair" }'
- code: invalid_currency_pair
category: invalid_currency_pair
message: The currency_pair should be the real market pair of the buy_currency and sell_currency
params: ''
- code: on_behalf_of_self
category: on_behalf_of
message: You cannot act on behalf of your own Contact
params: ''
- code: contact_not_found
category: on_behalf_of
message: Contact was not found for this id
params: ''
- code: on_behalf_of_is_not_valid_uuid
category: on_behalf_of
message: on_behalf_of should be in UUID format
params: ''
- code: on_behalf_of_is_required
category: on_behalf_of
message: You should do this conversion on behalf of someone if you supply client_rate
params: ''
- code: currency_pair_is_required
category: currency_pair_is_required
message: The currency_pair is required if you supply client_rate
params: ''
- code: variable_value_dates_not_permitted
category: variable_value_dates_not_permitted
message: 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.
params: ''
- code: client_buy_amount_is_in_invalid_format
category: client_buy_amount
message: client_buy_amount should be of numeric type with 2 dp
params: '{ "type" => "client_buy_amount" }'
- code: client_sell_amount_is_in_invalid_format
category: client_sell_amount
message: client_sell_amount should be of numeric type with 2 dp
params: '{ "type" => "client_sell_amount" }'
- code: cannot_fix_client_sell_on_fixed_sell_side
category: cannot_fix_client_sell_on_fixed_sell_side
message: You cannot specify a fixed client_sell_amount when the fixed side for a conversion is the sell side
params: '{ "type" => "client_sell_amount" }'
- code: client_buy_amount_exceeds_partner_buy_amount
category: client_buy_amount_exceeds_partner_buy_amount
message: The client buy amount specified is greater than the amount that you would be buying and is thus invalid
params: '{ "type" => "client_buy_amount" }'
- code: partner_sell_amount_exceeds_client_sell_amount
category: partner_sell_amount_exceeds_client_sell_amount
message: The client sell amount specified is less than the amount that you would be selling and is thus invalid
params: '{ "type" => "client_sell_amount" }'
- code: missing_partner_spread_table_data
category: missing_partner_spread_table_data
message: Sorry, the online partner pricing for the amount of the currency pair you are trying to trade has not been set up
params: ''
- code: missing_client_spread_table_data
category: missing_client_spread_table_data
message: Sorry, the online client pricing for the amount of the currency pair you are trying to trade has not been set up
params: ''
- code: fixed_amounts_not_permitted_for_this_user
category: fixed_amounts_not_permitted_for_this_user
message: You are not permitted to specify a fixed client_buy_amount or client_sell_amount for this customer
params: ''
- code: invalid_client_rate_combination
category: invalid_client_rate_combination
message: You cannot specify a client rate and client currency pair alongside a client buy amount or client sell amount
params: ''
- code: duplicate_request
category: duplicate_request
message: The unique_request_id provided for this conversion has already been used, please provide a new unique_request_id to successfully submit this conversion
params: ''
- code: invalid_conversion_date_combination
category: base
message: conversion_date_preference can not be specified along side a date parameter
params: ''
- code: invalid_conversion_date_preference
category: base
message: not a valid conversion date preference, possible options are earliest, optimize_liquidity, default, next_day
params: ''
schema:
$ref: '#/definitions/CreateConversionError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'404':
description: Resource not found.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'429':
description: Too many requests.
x-errors:
- code: too_many_requests
category: base
message: Too many requests have been made to the api. Please refer to the Developer Center for more information
params: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
default:
description: Unexpected error.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
/conversions/{id}:
get:
tags:
- Conversions
x-api-group: convert
summary: Get Conversion
description: Gets a conversion record for the provided unique ID.
operationId: GetConversion
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: id
in: path
required: true
type: string
description: Conversion UUID, this is returned by a successful trade request when creating a conversion.
format: uuid
- name: on_behalf_of
in: query
required: false
type: string
description: A contact UUID for the sub-account you're acting on behalf of.
format: uuid
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/Conversion'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'400':
description: Client error.
x-errors:
- code: id_is_not_valid_uuid
category: id
message: id should be in UUID format
params: ''
- code: on_behalf_of_self
category: on_behalf_of
message: You cannot act on behalf of your own Contact
params: ''
- code: contact_not_found
category: on_behalf_of
message: Contact was not found for this id
params: ''
schema:
$ref: '#/definitions/GetConversionError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'404':
description: Resource not found.
schema:
$ref: '#/definitions/NotFoundError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'429':
description: Too many requests.
x-errors:
- code: too_many_requests
category: base
message: Too many requests have been made to the api. Please refer to the Developer Center for more information
params: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
default:
description: Unexpected error.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
/conversions/find:
get:
tags:
- Conversions
x-api-group: convert
summary: Find Conversions
description: Finds conversions based on search parameters. If no search parameters are provided, all conversions under the house account are returned.
operationId: FindConversions
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: on_behalf_of
in: query
required: false
type: string
description: A contact UUID for the sub-account you're acting on behalf of.
format: uuid
- name: short_reference
in: query
required: false
type: string
description: Short reference code.
minLength: 1
maxLength: 25
- name: status
in: query
required: false
type: string
enum:
- awaiting_funds
- closed
- funds_arrived
- funds_sent
- trade_settled
description: Conversion status.
- name: buy_currency
in: query
required: false
type: string
description: Three-character ISO code of the currency being purchased.
format: iso-4217
pattern: ^[A-Z]{3}$
- name: sell_currency
in: query
required: false
type: string
description: Three-character ISO code of the currency being sold.
format: iso-4217
pattern: ^[A-Z]{3}$
- name: conversion_ids[]
in: query
required: false
type: array
items:
type: string
description: One or more conversion UUIDs to filter out of results.
format: uuid
- name: created_at_from
in: query
required: false
type: string
description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
format: date
- name: created_at_to
in: query
required: false
type: string
description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
format: date
- name: updated_at_from
in: query
required: false
type: string
description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
format: date
- name: updated_at_to
in: query
required: false
type: string
description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
format: date
- name: conversion_date_from
in: query
required: false
type: string
description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
format: date
- name: conversion_date_to
in: query
required: false
type: string
description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
format: date
- name: currency_pair
in: query
required: false
type: string
description: Concatenated string of the two three-character ISO codes for the currencies traded, e.g. "USDEUR".
pattern: ^[A-Z]{6}$
- name: partner_buy_amount_from
in: query
required: false
type: string
description: Minimum buy amount (sub-accounts).
pattern: ^\d+(\.\d{1,3})?$
- name: partner_buy_amount_to
in: query
required: false
type: string
description: Maximum buy amount (sub-accounts).
pattern: ^\d+(\.\d{1,3})?$
- name: partner_sell_amount_from
in: query
required: false
type: string
description: Minimum sell amount (sub-accounts).
pattern: ^\d+(\.\d{1,3})?$
- name: partner_sell_amount_to
in: query
required: false
type: string
description: Maximum sell amount (sub-accounts).
pattern: ^\d+(\.\d{1,3})?$
- name: buy_amount_from
in: query
required: false
type: string
description: Minimum buy amount.
pattern: ^\d+(\.\d{1,3})?$
- name: buy_amount_to
in: query
required: false
type: string
description: Maximum buy amount.
pattern: ^\d+(\.\d{1,3})?$
- name: sell_amount_from
in: query
required: false
type: string
description: Minimum sell amount.
pattern: ^\d+(\.\d{1,3})?$
- name: sell_amount_to
in: query
required: false
type: string
description: Maximum sell amount.
pattern: ^\d+(\.\d{1,3})?$
- name: scope
in: query
required: false
type: string
enum:
- all
- clients
- own
default: own
description: '"Own" account, "clients" sub-accounts, or "all" accounts. Default is "own".'
- name: settlement_date_from
in: query
required: false
type: string
description: Earliest date when sold currency debited. Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
format: date
- name: settlement_date_to
in: query
required: false
type: string
description: Latest date when sold currency debited. Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
format: date
- name: unique_request_id
in: query
required: false
type: string
description: User-generated idempotency key.
minLength: 1
maxLength: 255
- name: page
in: query
required: false
type: integer
description: Page number.
pattern: ^\d+$
- name: per_page
in: query
required: false
type: integer
description: Number of results per page.
pattern: ^\d+$
- name: order
in: query
required: false
type: string
description: Any field name to change the sort order.
minLength: 1
maxLength: 255
- name: order_asc_desc
in: query
required: false
type: string
enum:
- asc
- desc
default: asc
description: Sort records in ascending or descending order.
responses:
'200':
description: Success.
schema:
type: object
properties:
conversions:
type: array
items:
$ref: '#/definitions/Conversion'
pagination:
$ref: '#/definitions/Pagination'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'400':
description: Client error.
x-errors:
- code: on_behalf_of_self
category: on_behalf_of
message: You cannot act on behalf of your own Contact
params: ''
- code: contact_not_found
category: on_behalf_of
message: Contact was not found for this id
params: ''
schema:
$ref: '#/definitions/FindConversionsError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'404':
description: Resource not found.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'429':
description: Too many requests.
x-errors:
- code: too_many_requests
category: base
message: Too many requests have been made to the api. Please refer to the Developer Center for more information
params: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
default:
description: Unexpected error.
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
/conversions/{id}/cancellation_quote:
get:
tags:
- Conversions
x-api-group: convert
summary: Quote Conversion Cancellation
description: Gets a quote of the projected cost to cancel a conversion identified by a provided unique ID {id}.
operationId: ConversionCancellationQuote
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: id
in: path
required: true
type: string
description: Conversion UUID, this is returned by a successful trade request when creating a conversion.
format: uuid
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/ConversionCancellationQuote'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'400':
description: Client error.
x-errors:
- code: id_is_not_valid_uuid
category: id
message: id should be in UUID format
params: ''
- code: on_behalf_of_self
category: on_behalf_of
message: You cannot act on behalf of your own Contact
params: ''
- code: contact_not_found
category: on_behalf_of
message: Contact was not found for this id
params: ''
schema:
$ref: '#/definitions/GetConversionError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'401':
description: Unauthorized.
x-errors:
- code: invalid_supplied_credentials
category: username
message: Authentication failed with the supplied credentials
params: ''
schema:
$ref: '#/definitions/UnauthorizedError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'404':
description: Resource not found.
schema:
$ref: '#/definitions/NotFoundError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'429':
description: Too many requests.
x-errors:
- code: too_many_requests
category: base
message: Too many requests have been made to the api. Please refer to the Developer Center for more information
params: ''
schema:
$ref: '#/definitions/RateLimitError'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'500':
description: Internal server error
x-errors:
- code: internal_server_error
category: base
message: Internal server error
params: ''
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'503':
description: Service is temporary unavailable
x-errors:
- code: service_unavailable
category: base
message: Service is temporarily unavailable
params: ''
headers:
X-Request-Id:
# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/currencycloud/refs/heads/main/openapi/currencycloud-conversions-api-openapi.yml