Currencycloud API v2

swagger: '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 API
  termsOfService: 'https://www.currencycloud.com/terms-and-conditions/'
  contact:
    name: support
    email: support@currencycloud.com
externalDocs:
  description: API overview
  url: 'https://www.currencycloud.com/developers/'
tags:
  - name: Authenticate
    description: >-
      Authenticate to gain access to the API. Log in to
      your Currencycloud account using your API Key and log out to terminate
      your session.
  - name: Accounts
    description: >-
      Create, search and update your Currencycloud account and any associated
      sub-accounts. Also provides you with the ability to use your own reference
      IDs for easy reconciliation with your internal systems.
  - name: Balances
    description: >-
      Provides access to view balance information. View the balances that you
      currently hold in different currencies on your Currencycloud account.
  - name: Beneficiaries
    description: >-
      Create, search and manage the list of
      individuals or companies that you send payments to.
  - name: Contacts
    description: >-
      Create, search and manage the list of users that have access in your
      Currencycloud account or associated sub-accounts.
  - 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.
  - name: Funding
    description: >-
      Find funding accounts that can be used to settle
      and collect funds in each available currency.
  - name: Payers
    description: >-
      View information relating to the 'payer'
      for a payment that has been initiated through the platform.
  - name: Payments
    description: >-
      Create, search, manage and action all of your domestic and international
      payments through this API.
  - name: Quotes
    description: >-
      Create new quotes to use for held rates conversions.
  - name: Rates
    description: >-
      Super fast real-time access to live foreign exchange rates through the
      Currencycloud platform.
  - name: Reference
    description: >-
      Easy access to view important data relevant to your Currencycloud account
      including beneficiary details, conversion dates, available currencies,
      payer required details, payment dates and settlement details.
  - name: Reporting
    description: Ability to create and retrieve reports.
  - name: Sender
    description: Sender of funds.
  - name: Transactions
    description: >-
      View balances and all pending and completed transactions in your
      Currencycloud account, as well as associated sub-account balances and
      transactions.
  - name: Transfers
    description: >-
      Search, retrieve and create a transfer of funds between your Currencycloud
      account and associated sub-accounts.
  - name: Withdrawal Accounts
    description: >-
      Manage withdrawal accounts
  - name: Demo
    description: >-
      Requests that are only available in the Demo environment.
schemes:
  - https
host: devapi.currencycloud.com
basePath: /v2
consumes:
  - multipart/form-data
produces:
  - application/json
paths:
  /authenticate/api:
    post:
      tags:
        - Authenticate
      x-api-group: manage
      summary: Login
      description: >-
        Authenticates and authorizes a user to the Currencycloud API.<br><br>

        Submit a login ID and API key for a Currencycloud account, you can register
        for and API key <a href="https://developer.currencycloud.com/register-for-an-api-key/">here</a>.
        A temporary authentication token is returned following a succesful login.<br><br>

        The authentication token is required to make requests to all other
        endpoints in the Currencycloud API. Tokens expire after 30 minutes of
        inactivity.<br><br>

        Token requests are limited to 60 calls per minute.<br><br>

        For security, Currencycloud accounts are disabled when four unsuccessful
        login attempts are made within a short period. In these circumstances, account
        holders must <a href="mailto:support@currencycloud.com">contact support</a> to
        reactivate their account.
      operationId: Login
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - name: login_id
          in: formData
          required: true
          type: string
          description: >-
            The login ID for a Currencycloud account, this is usually an email
            address.
          minLength: 1
          maxLength: 50
        - name: api_key
          in: formData
          required: true
          type: string
          description: The unique API key for the Currencycloud account.
          pattern: ^[a-f0-9]{64}$
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/AuthenticationToken'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
            - code: login_id_is_required
              category: login_id
              message: login_id is required
              params: ''
            - code: login_id_is_too_short
              category: login_id
              message: login_id can not be shorter than 1 character(s)
              params: '{ "minlength" => 1 }'
            - code: login_id_is_too_long
              category: login_id
              message: login_id can not be longer than 255 character(s)
              params: '{ "maxlength" => 255 }'
            - code: api_key_is_required
              category: api_key
              message: api_key is required
              params: ''
            - code: api_key_length_is_invalid
              category: api_key
              message: api_key should be 64 character(s) long
              params: '{ "length" => 64 }'
          schema:
            $ref: '#/definitions/LoginError'
          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 temporarily 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.
  /authenticate/close_session:
    post:
      tags:
        - Authenticate
      x-api-group: manage
      summary: Logout
      description: >-
        Authentication tokens expire automatically after 30 minutes of
        inactivity. If a session is no longer required, it is good security
        practice to retire its authentication token early rather than leave it
        to time out.
      operationId: Logout
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - name: X-Auth-Token
          in: header
          required: true
          type: string
          description: Authentication token
          minLength: 32
      responses:
        '200':
          description: >-
            Success. A 200 response with an empty payload signifies that the
            authentication token is successfully retired.
          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.
  /accounts/create:
    post:
      tags:
        - Accounts
      x-api-group: manage
      summary: Create Account
      description: 'Creates a new sub-account. Returns the new account entity on success.'
      operationId: CreateAccount
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - name: X-Auth-Token
          in: header
          required: true
          type: string
          description: Authentication token
          minLength: 32
        - name: account_name
          in: formData
          required: true
          type: string
          description: Account name.
          pattern: \S+
          minLength: 1
          maxLength: 150
        - name: legal_entity_type
          in: formData
          required: true
          type: string
          enum:
            - company
            - individual
          description: Legal entity.
        - name: street
          in: formData
          required: true
          type: string
          description: First line of address.
          maxLength: 150
        - name: city
          in: formData
          required: true
          type: string
          description: City
          maxLength: 100
        - name: postal_code
          in: formData
          required: false
          type: string
          description: Postal code. Required for sub-accounts on our outsourced KYC model, also required where country code = "US", "CA" or "MX".
          maxLength: 20
        - name: country
          in: formData
          required: true
          type: string
          description: Two-letter ISO country code.
          format: iso3166-1-alpha-2
          pattern: ^[A-Z]{2}$
        - name: brand
          in: formData
          required: false
          type: string
          description: >-
            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.
          minLength: 1
          maxLength: 255
        - name: your_reference
          in: formData
          required: false
          type: string
          description: User-generated reference code.
          minLength: 1
          maxLength: 255
        - name: status
          in: formData
          required: false
          type: string
          enum:
            - disabled
            - enabled
          default: enabled
          description: Account status.
        - name: state_or_province
          in: formData
          required: false
          type: string
          description: State or province two-letter ISO 3166 code. Only applicable to some countries, required where country code = "US", "CA" or "MX".
          maxLength: 100
        - name: spread_table
          in: formData
          required: false
          type: string
          default: flat_0.00
          description: The name of the spread table assigned to the account. This is needed if they intend to apply markup.
          maxLength: 100
        - name: api_trading
          in: formData
          required: false
          type: boolean
          description: Allow the account to make trades via the Currencycloud API.
        - name: online_trading
          in: formData
          required: false
          type: boolean
          description: Allow the account to make trades via Currencycloud Direct.
        - name: phone_trading
          in: formData
          required: false
          type: boolean
          description: Allow the account to make trades via phone.
        - name: identification_type
          in: formData
          required: false
          type: string
          enum:
            - none
            - others
            - asylum_registration_card
            - citizenship_papers
            - consular_id
            - credential_de_elector
            - drivers_license
            - drivers_license_canadian
            - employer_identification_number
            - existing_credit_card_details
            - green_card
            - immigration_status_document
            - indigenous_card
            - international_driving_licence
            - matricula_consular
            - municipality_identity_card
            - national_health_insurance_card
            - national_id
            - national_identity_card
            - passport
            - passport_card
            - postal_identity_card
            - private_operators_card
            - professional_qualification_card
            - proof_of_citizenship
            - registro_federal_de_contribuyentes
            - residence_permit
            - residence_status_document
            - service_id_card
            - social_insurance_number
            - social_security_card
            - social_security_number
            - tax_id
            - visa
            - voter_id
            - work_permit
            - incorporation_number
          description: A legal document that verifies the identity of the account owner. Required for individual sub-accounts on our outsourced KYC model, optional otherwise.
        - name: identification_value
          in: formData
          required: false
          type: string
          description: >-
            Unique reference code for the identification document, such as a
            passport number. Required if "identification_type" is provided.
          minLength: 1
          maxLength: 255
        - name: terms_and_conditions_accepted
          in: formData
          required: false
          type: boolean
          description: Acceptance of the terms and conditions. Required for sub-accounts that are on our Outsourced KYC model, optional otherwise.
        - name: industry_type
          in: formData
          required: false
          maxLength: 255
          type: string
          description: The industry the account operates in. Required if "linked_account_id" is present. Required if extended compliance fields are present.
        - name: business_website_url
          in: formData
          required: false
          type: string
          maxLength: 400
          description: >-
            A fully qualified URL (including scheme) indicating a marketplace homepage, a link to a government page concerning the company or the literal string 'no_website_available'. Required if extended compliance fields are present.
        - name: identification_expiration
          in: formData
          required: false
          type: string
          format: date
          description: >-
            The expiration date for the identification information provided. Format YYYY-MM-DD. Part of extended compliance for "legal_entity_type: individual" accounts.
        - name: identification_issuer
          in: formData
          maxLength: 255
          required: false
          type: string
          description: >-
            ISO country code indicating the issuer of the identification information provided. Part of extended compliance for "legal_entity_type: individual" accounts.
        - name: country_of_citizenship
          in: formData
          required: false
          type: string
          description: >-
            ISO country code indicating the citizenship of the individual the account belongs to. Provide the longest held citizenship for individuals with multiple. Part of extended compliance for "legal_entity_type: individual" accounts.
        - name: country_of_incorporation
          in: formData
          required: false
          type: string
          maxLength: 2
          minLength: 2
          description: >-
            Two-letter ISO country code indicating the country the company is incorpated in. Part of extended compliance for "legal_entity_type: company" accounts.
        - name: date_of_incorporation
          in: formData
          required: false
          type: string
          format: date
          description: >-
            Date of the company's incorporation. Part of extended compliance for "legal_entity_type: company" accounts.
        - name: legal_entity_sub_type
          in: formData
          required: false
          type: string
          description: >-
            The type of company this account represents. Part of extended compliance for "legal_entity_type: company" accounts.
          enum:
            - sole_trader
            - limited_liability_company
            - public_limited_company
            - limited_liability_partnership
            - unincorporated_partnership
            - unregistered_charity
            - registered_charity
            - trust
            - company_with_nominee_shareholders_or_shares_in_bearer_form
            - scottish_limited_partnership
            - other
        - name: trading_address_street
          in: formData
          required: false
          type: string
          maxLength: 150
          description: >-
            The street portion of the company's trading address. Part of extended compliance for "legal_entity_type: company" accounts.
        - name: trading_address_city
          in: formData
          required: false
          type: string
          description: >-
            The city portion of the company's trading address. Part of extended compliance for "legal_entity_type: company" accounts.
        - name: trading_address_state
          in: formData
          required: false
          type: string
          maxLength: 100
          description: >-
            The state portion of the company's trading address. Part of extended compliance for "legal_entity_type: company" accounts.
        - name: trading_address_postalcode
          in: formData
          required: false
          type: string
          maxLength: 20
          description: >-
            The postal code portion of the company's trading address. Part of extended compliance for "legal_entity_type: company" accounts.
        - name: trading_address_country
          in: formData
          required: false
          maxLength: 2
          minLength: 2
          type: string
          description: >-
            Two-letter ISO country code representing the country portion of the company's trading address.
            Part of extended compliance for accounts with "legal_entity_type: company".
        - name: tax_identification
          in: formData
          required: false
          type: string
          maxLength: 100
          description: >-
            Tax identification number for the company. Part of extended compliance for accounts with "legal_entity_type: company". Required for companies based in "US" or "AU".
        - name: national_identification
          in: formData
          required: false
          type: string
          maxLength: 100
          description: >-
            National identification (e.g SSN for U.S. individuals). Part of extended compliance for "legal_entity_type: individual" accounts. Required for "US" based companies.
        - name: customer_risk
          in: formData
          required: false
          type: string
          description: >-
            The risk classification for this account's expected behaviour. Part of extended compliance for "legal_entity_type: individual | company" accounts.
          enum:
            - LOW
            - MEDIUM
            - HIGH
        - name: expected_monthly_activity_volume
          in: formData
          required: false
          type: number
          description: >-
            The expected number of money moving actions this account will conduct monthly. Part of extended compliance for "legal_entity_type: individual | company" accounts.
        - name: expected_monthly_activity_value
          in: formData
          required: false
          type: number
          description: >-
            The expected sum value of money moving actions this account will conduct monthly. The currency basis of the value is submitted as part of "expected_transaction_currencies". Part of extended compliance for "legal_entity_type: individual | company" accounts.
        - name: 'expected_transaction_currencies[]'
          in: formData
          required: false
          description: >-
            An array holding a single ISO currency code for the expected currency this account will mainly transact in. Part of extended compliance for "legal_entity_type: individual | company" accounts.
          type: array
          items:
            type: string
        - name: 'expected_transaction_countries[]'
          in: formData
          required: false
          type: array
          description: Array of two-letter ISO-3166 country codes indicating the countries this account is expected to transact to and from.
          items:
            type: string
            minLength: 2
            maxLength: 2
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/Account'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
            - code: account_name_is_too_short
              category: account_name
              message: account_name can not be shorter than 1 character(s)
              params: '{ "minlength" => 1 }'
            - code: account_name_is_too_long
              category: account_name
              message: account_name can not be longer than 150 character(s)
              params: '{ "maxlength" => 150 }'
            - code: account_name_is_required
              category: account_name
              message: account_name is required
              params: ''
            - code: brand_is_too_short
              category: brand
              message: brand can not be shorter than 1 character(s)
              params: '{ "minlength" => 1 }'
            - code: brand_is_too_long
              category: brand
              message: brand can not be longer than 255 character(s)
              params: '{ "maxlength" => 255 }'
            - code: brand_not_found
              category: brand
              message: Brand non_existing_brand wasn't found
              params: '{ "brand" => "non_existing_brand" }'
            - code: brand_account_not_broker
              category: brand
              message: Account doesn't have broker permissions
              params: '{ "brand" => "wrong_brand" }'
            - code: your_reference_is_too_long
              category: your_reference
              message: your_reference can not be longer than 25 character(s)
              params: '{ "maxlength" => 25 }'
            - code: status_not_in_range
              category: status
              message: 'status should be in range: enabled, disabled'
              params: '{ "range" => "enabled, disabled" }'
            - code: legal_entity_type_not_in_range
              category: legal_entity_type
              message: 'legal_entity_type should be in range: individual, company'
              params: '{ "range" => "individual, company" }'
            - code: legal_entity_type_is_required
              category: legal_entity_type
              message: 'Legal entity type is required'
              params: ''
            - code: street_is_too_long
              category: street
              message: street can not be longer than 150 character(s)
              params: '{ "maxlength" => 150 }'
            - code: street_is_required
              category: street
              message: Street is required
              params: ''
            - code: city_is_too_long
              category: city
              message: city can not be longer than 100 character(s)
              params: '{ "maxlength" => 100 }'
            - code: city_is_required
              category: city
              message: City is required.
              params: ''
            - code: postal_code_is_too_long
              category: postal_code
              message: postal_code can not be longer than 20 character(s)
              params: '{ "maxlength" => 20 }'
            - code: postal_code_is_required
              category: postal_code
              message: Postal code is required.
              params: ''
            - code: state_or_province_is_too_long
              category: state_or_province
              message: state_or_province can not be longer than 100 character(s)
              params: '{ "maxlength" => 100 }'
            - code: country_is_in_invalid_format
              category: country
              message: country is not a valid ISO 3166-1 Alpha-2 country code
              params: '{ "maxlength" => 2 }'
            - code: country_is_required
              category: country
              message: Country is required
              params: ''
            - code: spread_table_is_too_long
              category: spread_table
              message: spread_table can not be longer than 100 character(s)
              params: '{ "maxlength" => 100 }'
            - code: identification_type_is_missing
              category: identification_type
              message: identification_type is missing
              params: ''
            - code: identification_type_is_invalid
              category: identification_type
              message: identification_type is invalid
              params: ''
            - code: identification_value_is_missing
              category: identification_value
              message: identification_value is missing
              params: ''
            - code: identification_value_is_invalid
              category: identification_value
              message: identification_value is invalid
              params: ''
            - code: state_or_province_is_required
              category: state_or_province
              message: 'State or province is required for US, CA and MX'
              params: ''
            - code: terms_and_conditions_accepted_is_required
              category: terms_and_conditions_accepted
              message: 'Terms and conditions accepted is required'
              params: ''
            - code: invalid_extra_parameters
              category: base
              message: Invalid extra parameters extra_parameter
              params: '{ "parameters" => "extra_parameter" }'
          schema:
            $ref: '#/definitions/CreateAccountError'
          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.
  /accounts/{id}:
   get:
    tags:
      - Accounts
    x-api-group: manage
    summary: Get Account
    description: Gets an account or sub-account owned by the authenticated user.
    operationId: GetAccount
    produces:
      - application/json
    parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
      - name: id
        in: path
        required: true
        type: string
        description: Account UUID, returned by the create account endpoint.
      - name: on_behalf_of
        in: query
        required: false
        type: string
        description: A contact UUID for the sub-account you're acting on behalf of.
    responses:
   

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