Currencycloud Conversions API

openapi: 3.2.0
info:
  description: The Currencycloud API is a robust, predictable, easy-to-use API for converting money between currencies and making payments around the world. Dynamically register sub-accounts to provide white labeled money transfer services to your own customers.
  version: 2.43.0
  title: Currencycloud Conversions API
  termsOfService: https://www.currencycloud.com/terms-and-conditions/
  contact:
    name: support
    email: support@currencycloud.com
servers:
- url: https://devapi.currencycloud.com/v2
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
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversion'
        '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: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConversionError'
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Resource not found.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '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: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                buy_currency:
                  type: string
                  format: iso-4217
                  pattern: ^[A-Z]{3}$
                  description: Three-character ISO code of the currency being purchased.
                sell_currency:
                  type: string
                  format: iso-4217
                  pattern: ^[A-Z]{3}$
                  description: Three-character ISO code for currency sold.
                fixed_side:
                  type: string
                  enum:
                  - buy
                  - sell
                  description: Fix the buy or sell currency.
                amount:
                  type: string
                  pattern: ^\d+(\.\d{1,3})?$
                  description: Amount of the fixed buy or sell currency.
                term_agreement:
                  type: boolean
                  enum:
                  - true
                  - false
                  description: Indicates agreement to terms and conditions.
                conversion_date:
                  type: string
                  format: date
                  description: Earliest delivery date in UTC time zone. Format YYYY-MM-DD.
                client_buy_amount:
                  type: string
                  pattern: ^\d+(\.\d{1,2})?$
                  description: Client buy amount.
                client_sell_amount:
                  type: string
                  pattern: ^\d+(\.\d{1,2})?$
                  description: Client sell amount.
                reason:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: User-generated reason for conversion - freeform text.
                unique_request_id:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: User-generated idempotency key. Beneficial for request tracking / management.
                on_behalf_of:
                  type: string
                  format: uuid
                  description: A contact UUID for the sub-account you're acting on behalf of.
                conversion_date_preference:
                  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.
                quote_id:
                  type: string
                  description: The UUID of a previously created conversion quote.
              required:
              - buy_currency
              - sell_currency
              - fixed_side
              - amount
              - term_agreement
  /conversions/{id}:
    get:
      tags:
      - Conversions
      x-api-group: convert
      summary: Get Conversion
      description: Gets a conversion record for the provided unique ID.
      operationId: GetConversion
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - name: id
        in: path
        required: true
        description: Conversion UUID, this is returned by a successful trade request when creating a conversion.
        schema:
          type: string
          format: uuid
      - name: on_behalf_of
        in: query
        required: false
        description: A contact UUID for the sub-account you're acting on behalf of.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversion'
        '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: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConversionError'
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Resource not found.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '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: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
  /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
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - name: on_behalf_of
        in: query
        required: false
        description: A contact UUID for the sub-account you're acting on behalf of.
        schema:
          type: string
          format: uuid
      - name: short_reference
        in: query
        required: false
        description: Short reference code.
        schema:
          type: string
          maxLength: 25
          minLength: 1
      - name: status
        in: query
        required: false
        description: Conversion status.
        schema:
          type: string
          enum:
          - awaiting_funds
          - closed
          - funds_arrived
          - funds_sent
          - trade_settled
      - name: buy_currency
        in: query
        required: false
        description: Three-character ISO code of the currency being purchased.
        schema:
          type: string
          format: iso-4217
          pattern: ^[A-Z]{3}$
      - name: sell_currency
        in: query
        required: false
        description: Three-character ISO code of the currency being sold.
        schema:
          type: string
          format: iso-4217
          pattern: ^[A-Z]{3}$
      - name: conversion_ids[]
        in: query
        required: false
        description: One or more conversion UUIDs to filter out of results.
        schema:
          type: array
          format: uuid
          items:
            type: string
      - name: created_at_from
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
        schema:
          type: string
          format: date
      - name: created_at_to
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
        schema:
          type: string
          format: date
      - name: updated_at_from
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
        schema:
          type: string
          format: date
      - name: updated_at_to
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
        schema:
          type: string
          format: date
      - name: conversion_date_from
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
        schema:
          type: string
          format: date
      - name: conversion_date_to
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
        schema:
          type: string
          format: date
      - name: currency_pair
        in: query
        required: false
        description: Concatenated string of the two three-character ISO codes for the currencies traded, e.g. "USDEUR".
        schema:
          type: string
          pattern: ^[A-Z]{6}$
      - name: partner_buy_amount_from
        in: query
        required: false
        description: Minimum buy amount (sub-accounts).
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: partner_buy_amount_to
        in: query
        required: false
        description: Maximum buy amount (sub-accounts).
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: partner_sell_amount_from
        in: query
        required: false
        description: Minimum sell amount (sub-accounts).
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: partner_sell_amount_to
        in: query
        required: false
        description: Maximum sell amount (sub-accounts).
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: buy_amount_from
        in: query
        required: false
        description: Minimum buy amount.
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: buy_amount_to
        in: query
        required: false
        description: Maximum buy amount.
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: sell_amount_from
        in: query
        required: false
        description: Minimum sell amount.
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: sell_amount_to
        in: query
        required: false
        description: Maximum sell amount.
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: scope
        in: query
        required: false
        description: '"Own" account, "clients" sub-accounts, or "all" accounts. Default is "own".'
        schema:
          type: string
          enum:
          - all
          - clients
          - own
          default: own
      - name: settlement_date_from
        in: query
        required: false
        description: Earliest date when sold currency debited. Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
        schema:
          type: string
          format: date
      - name: settlement_date_to
        in: query
        required: false
        description: Latest date when sold currency debited. Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
        schema:
          type: string
          format: date
      - name: unique_request_id
        in: query
        required: false
        description: User-generated idempotency key.
        schema:
          type: string
          maxLength: 255
          minLength: 1
      - name: page
        in: query
        required: false
        description: Page number.
        schema:
          type: integer
          pattern: ^\d+$
      - name: per_page
        in: query
        required: false
        description: Number of results per page.
        schema:
          type: integer
          pattern: ^\d+$
      - name: order
        in: query
        required: false
        description: Any field name to change the sort order.
        schema:
          type: string
          maxLength: 255
          minLength: 1
      - name: order_asc_desc
        in: query
        required: false
        description: Sort records in ascending or descending order.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Conversion'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '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: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindConversionsError'
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Resource not found.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '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: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
  /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
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - name: id
        in: path
        required: true
        description: Conversion UUID, this is returned by a successful trade request when creating a conversion.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversionCancellationQuote'
        '400':
          description: Client error.
          x-errors:
          - code: id_is_not_valid_uuid
            category: id
            message: id should be in UUID 

# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/currencycloud/refs/heads/main/openapi/currencycloud-conversions-api-openapi.yml