Currencycloud Accounts API

openapi: 3.0.3
info:
  title: api-onboarding Account Usage Accounts API
  version: v1
  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.
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: 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.
paths:
  /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:
        '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: id_is_not_valid_uuid
            category: id
            message: id should be in UUID format
            params: ''
          - code: account_not_found
            category: id
            message: Account was not found for this id
            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/GetAccountError'
          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.
    post:
      tags:
      - Accounts
      x-api-group: manage
      summary: Update Account
      description: Updates a sub-account owned by the authenticated user. The updated account entity is returned on success.
      operationId: UpdateAccount
      consumes:
      - multipart/form-data
      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: account_name
        in: formData
        required: false
        type: string
        description: Account name.
      - name: legal_entity_type
        in: formData
        required: false
        type: string
        enum:
        - company
        - individual
        description: Legal entity.
      - name: brand
        in: formData
        required: false
        type: string
        description: The value of this field is used for white labeling the Currencycloud user interface.
      - name: your_reference
        in: formData
        required: false
        type: string
        description: User-generated reference code.
      - name: status
        in: formData
        required: false
        type: string
        enum:
        - disabled
        - enabled
        default: enabled
        description: Status of the account.
      - name: street
        in: formData
        required: false
        type: string
        description: First line of address.
      - name: city
        in: formData
        required: false
        type: string
        description: City name
      - name: state_or_province
        in: formData
        required: false
        type: string
        description: State or province two-letter ISO 3166 code. Only applicable to some countries.
      - name: postal_code
        in: formData
        required: false
        type: string
        description: Postal code.
      - name: country
        in: formData
        required: false
        type: string
        description: Two-letter ISO country code.
      - name: spread_table
        in: formData
        required: false
        type: string
        default: fxcg_rfx_default
        description: The name of the spread table assigned to the account.
      - name: api_trading
        in: formData
        required: false
        type: boolean
        default: true
        description: Whether trading via the Currencycloud API is to be enabled on the account.
      - name: online_trading
        in: formData
        required: false
        type: boolean
        default: true
        description: Enable online trading on the account.
      - name: phone_trading
        in: formData
        required: false
        default: true
        type: boolean
        description: Enable phone trading on the account.
      - 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.
      - name: identification_value
        in: formData
        required: false
        type: string
        description: A unique reference code for the identification document, such as a passport number.
        maxLength: 255
      - name: terms_and_conditions_accepted
        in: formData
        required: false
        type: boolean
        description: Acceptance of the terms and conditions.
      - 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
        required: false
        type: string
        maxLength: 255
        description: 'ISO country code indicating the issuer of the identification information provided. Part of extended compliance for "legal_entity_type: individual" 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
      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: at_least_one_parameter
            category: base
            message: 'At least one parameter should be present: account_name, brand, your_reference, status, street, city, state_or_province, postal_code, country, spread_table, legal_entity_type, identification_type, identification_value, api_trading, online_trading, phone_trading or terms_and_conditions_accepted.'
            params: '{ account_name, brand, your_reference, status, street, city, state_or_province, postal_code, country, spread_table, legal_entity_type, identification_type, identification_value, api_trading, online_trading, phone_trading, terms_and_conditions_accepted }'
          - code: id_is_not_valid_uuid
            category: id
            message: id should be in UUID format
            params: ''
          - 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_in_invalid_format
            category: account_name
            message: account_name is in invalid format
            params: ''
          - 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: permission_denied
            category: permissions
            message: Permission denied
            params: ''
          - code: your_reference_is_too_long
            category: your_reference
            message: your_reference can not be longer than 25 character(s)
            params: '{ "maxlength" => 25 }'
          - code: legal_entity_type_not_in_range
            category: legal_entity_type
            message: 'legal_entity_type shoul

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