# Upvest Investment API Upvest Investment API. Version: 1.148.0 License: Apache 2.0 ## Servers Sandbox environment ``` https://sandbox.upvest.co ``` Live environment ``` https://api.upvest.co ``` ## Security ### oauth-client-credentials Type: oauth2 Token URL: https://sandbox.upvest.co/auth/token Scopes: - `accounts:read`: Read accounts and account groups - `accounts:admin`: Create/update/delete accounts and account groups - `webhooks:admin`: Create/update/delete webhooks - `webhooks:read`: Read webhooks - `files:read`: Read files metadata - `orders:admin`: Create/update/delete orders - `orders:read`: Read orders - `users:admin`: Create/update/delete users - `users:read`: Read users - `checks:admin`: Create checks - `checks:read`: Read checks - `positions:read`: Read positions - `positions_performance:read`: Read positions performance - `reference_accounts:admin`: Create/update/delete reference accounts - `reference_accounts:read`: Read reference accounts - `mandates:admin`: Create/update/delete mandates - `mandates:read`: Read mandates - `payments:admin`: Payins and withdrawal operations - `payments:read`: Payins and withdrawal read operations - `topups:admin`: Top-ups operations - `topups:read`: Top-ups read operations - `cash_balance_transfers:admin`: Cash balance transfer operations - `cash_balance_transfers:read`: Cash balance transfer read operations - `credit_fundings:read`: Credit Fundings read operations - `securities_transfers:read`: Securities Transfers read transfers - `securities_transfers:admin`: Securities Transfers operations - `isa_transfers:admin`: ISA Transfers operations - `reports:read`: Read reports - `reports:admin`: Create reports - `taxes:read`: Read tax residencies - `taxes:admin`: Modify tax residencies and tax exemptions - `transactions:read`: Read cash and securities transactions - `instruments:read`: Read instruments - `fees:admin`: Create and read fee operations - `fees:read`: Read fee operations - `transaction_fees:admin`: Create and read transaction fee operations - `transaction_fees:read`: Read transaction fee operations - `portfolios:read`: Read portfolios - `portfolios:admin`: Modify portfolios - `valuations:read`: Read valuations - `account_liquidations:read`: Read accounts liquidations - `account_liquidations:admin`: Trigger/read/cancel accounts liquidations - `account_returns:read`: Read accounts returns - `virtual_cash_balances:admin`: Virtual cash balances - `savings_plans:read`: Read savings plans - `savings_plans:admin`: Create/read savings plans - `prices:read`: Read instrument prices, - `tests:admin`: Testing related operations - `account_transfers:read`: Account Transfers read transfers - `account_transfers:admin`: Account Transfers operations - `businesses:admin`: Create/update/delete businesses, - `businesses:read`: Read businesses, - `roles:admin`: Create/update/deactivate roles - `roles:read`: Read roles - `corporate_actions:admin`: Create/update/delete corporate action instructions ## Download OpenAPI description - [Upvest Investment API](https://docs.upvest.co/_bundle/api.yaml) ## Access Tokens - [POST /auth/token](https://docs.upvest.co/api/access-tokens/issue_token.md): Get an access token to use with the API with specified scopes. You should *always* scope your access tokens. You get one for read-access and separate ones for updating, creating or deleting resources. ## Users - [GET /users](https://docs.upvest.co/api/users/list_users.md): Returns a paginated list of users. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching users. Use `sort`/`order` to control ord - [POST /users](https://docs.upvest.co/api/users/create_user.md): Creates a user. The user must complete identity checks and provide any required identifiers before activation. See the Creating a user guide ([TOL](https://docs.upvest.co/products/tol/guides/users/use - [GET /users/{user_id}](https://docs.upvest.co/api/users/retrieve_user.md): Returns the user identified by `user_id`, including profile and status details - [DELETE /users/{user_id}](https://docs.upvest.co/api/users/offboard_user.md): Starts the user offboarding process in the background. - [POST /users/{user_id}/data_change_requests](https://docs.upvest.co/api/users/user_data_change.md): Requests a data change for a user specified by ID. - [POST Users events](https://docs.upvest.co/api/users/user_event.md): Notifies subscribers of user lifecycle events. Triggered when a user is created, activated, deactivated, offboarded, or has a data change processed or rejected. See the User webhook events guide ([TOL ## User Identifiers - [GET /users/{user_id}/identifiers](https://docs.upvest.co/api/user-identifiers/list_user_identifiers.md): Lists all existing identifiers of a user used for transaction reporting. - [POST /users/{user_id}/identifiers](https://docs.upvest.co/api/user-identifiers/create_identifier.md): Creates a new identifier for a user that will be used for transaction reporting obligations. This identifier is required for user activation if the user's nationalities do not allow reporting using th - [GET /users/{user_id}/identifiers/{identifier_id}](https://docs.upvest.co/api/user-identifiers/retrieve_identifier.md): Returns an existing identifier of a given user used for transaction reporting. - [PATCH /users/{user_id}/identifiers/{identifier_id}](https://docs.upvest.co/api/user-identifiers/update_identifier.md): Updates an existing identifier of a given user used for transaction reporting. ## User Checks - [GET /users/{user_id}/checks](https://docs.upvest.co/api/user-checks/list_user_checks.md): Lists all checks for a user specified by ID. - [POST /users/{user_id}/checks](https://docs.upvest.co/api/user-checks/create_user_check.md): Creates a new check for a user specified by ID. - [GET /users/{user_id}/checks/{check_id}](https://docs.upvest.co/api/user-checks/retrieve_user_check.md): Retrieves a check for a user specified by its ID. - [POST User checks events](https://docs.upvest.co/api/user-checks/user_checks_event.md): Notifies subscribers of user check lifecycle events. Triggered when a check is created, passed, or failed for a user. See the Conducting regulatory checks guide ([TOL](https://docs.upvest.co/products/ ## Businesses - [GET /businesses](https://docs.upvest.co/api/businesses/list_businesses.md): Returns a paginated list of all businesses. Use `offset` and `limit` to paginate through results, and `sort`/`order` to control the ordering by `created_at` or `updated_at`. See the Business accounts - [POST /businesses](https://docs.upvest.co/api/businesses/create_business.md): Creates a business. Supports both corporate and sole trader business types, each with a different set of required fields. See the Business accounts guide ([TOL](https://docs.upvest.co/products/tol/gui - [GET /businesses/{business_id}](https://docs.upvest.co/api/businesses/retrieve_business.md): Returns the business identified by `business_id`, including profile and status details - [POST /businesses/{business_id}/data_change_requests](https://docs.upvest.co/api/businesses/business_data_change.md): Requests a data change for a business specified by ID. - [POST Business events](https://docs.upvest.co/api/businesses/business_event.md): Notifies subscribers of business lifecycle events. Triggered when a business is created, activated, deactivated, offboarded, or has a data change processed or rejected. See the Business accounts guide ## Business Checks - [GET /businesses/{business_id}/checks](https://docs.upvest.co/api/business-checks/list_business_checks.md): Lists all checks for a business specified by ID. - [POST /businesses/{business_id}/checks](https://docs.upvest.co/api/business-checks/create_business_check.md): Creates a new check for a business specified by ID. - [GET /businesses/{business_id}/checks/{check_id}](https://docs.upvest.co/api/business-checks/retrieve_business_check.md): Retrieves a check for a business specified by its ID. - [POST Business checks events](https://docs.upvest.co/api/business-checks/business_checks_event.md): Notifies subscribers of business check lifecycle events. Triggered when a check is created, passed, or failed for a business. See the Creating a corporate business account guide ([TOL](https://docs.up ## Roles - [GET /roles](https://docs.upvest.co/api/roles/list_roles.md): Returns a paginated list of roles. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching roles. Use `user_id` to filter by a spec - [POST /roles](https://docs.upvest.co/api/roles/create_role.md): Creates a role, assigning a user to an account group or business entity. The `entity_type` parameter determines whether `entity_id` refers to an account group or a business, and constrains which `role - [GET /roles/{role_id}](https://docs.upvest.co/api/roles/retrieve_role.md): Returns the role identified by `role_id`, including its status and entity assignment. - [DELETE /roles/{role_id}](https://docs.upvest.co/api/roles/role_deactivation.md): Deactivates the role specified by its ID. The role remains queryable with status `DEACTIVATED`. Only roles whose `entity_type` is `BUSINESS` may be deactivated via this endpoint; account-group roles a - [POST Role events](https://docs.upvest.co/api/roles/role_event.md): Notifies subscribers of role lifecycle events. Triggered when a role is created, activated, or deactivated. See the User roles guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_onboa ## Tax Residencies - [GET /users/{user_id}/tax_residencies](https://docs.upvest.co/api/tax-residencies/retrieve_tax_residencies.md): Returns the tax residencies currently on file for the user identified by `user_id`. See the User tax onboarding guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_tax_onboarding) / [B - [POST /users/{user_id}/tax_residencies](https://docs.upvest.co/api/tax-residencies/set_tax_residencies.md): Records the tax residencies for the user identified by `user_id`, replacing any previously submitted set. See the User tax onboarding guide ([TOL](https://docs.upvest.co/products/tol/guides/users/user ## Accounts - [GET /users/{user_id}/accounts](https://docs.upvest.co/api/accounts/list_user_accounts.md): Lists the accounts of a user specified by ID. - [GET /accounts/{account_id}](https://docs.upvest.co/api/accounts/retrieve_account.md): Returns the account specified by its ID, including its type, status, and the account group it belongs to. - [PATCH /accounts/{account_id}](https://docs.upvest.co/api/accounts/update_account.md): Updates the account specified by its ID. Only the account `name` can be updated. Returns the full updated account object. - [DELETE /accounts/{account_id}](https://docs.upvest.co/api/accounts/account_closure.md): Initiates the closure of the account specified by its ID. Closure is a two-step process: the account status changes to `CLOSING`, and once all preconditions are met the account transitions to `CLOSED` - [GET /accounts](https://docs.upvest.co/api/accounts/list_accounts.md): Returns a paginated list of accounts. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching accounts. Both user and business acco - [POST /accounts](https://docs.upvest.co/api/accounts/create_account.md): Creates an account for a user or a business within an existing account group. The account is created with status `PENDING_APPROVAL` and switches to `ACTIVE` once the owner's onboarding is complete; su - [GET /businesses/{business_id}/accounts](https://docs.upvest.co/api/accounts/list_business_accounts.md): Lists the accounts of a business specified by ID. - [POST Account events](https://docs.upvest.co/api/accounts/account_event.md): Notifies subscribers of account lifecycle events. Triggered when an account is created, activated, updated, locked, closed, or has its closure initiated. See the Account webhooks guide ([TOL](https:// ## Account Groups - [GET /users/{user_id}/account_groups](https://docs.upvest.co/api/account-groups/list_user_account_groups.md): Lists the account groups of a user specified by ID. - [GET /account_groups/{account_group_id}](https://docs.upvest.co/api/account-groups/retrieve_account_group.md): Returns the account group specified by its ID, including its type, status, and securities account number. - [DELETE /account_groups/{account_group_id}](https://docs.upvest.co/api/account-groups/account_group_closure.md): Initiates the closure of the account group specified by its ID. Closure is a two-step process: the account group status changes to `CLOSING`, and once all preconditions are met it transitions to `CLOS - [GET /account_groups](https://docs.upvest.co/api/account-groups/list_account_groups.md): Returns a paginated list of account groups. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching account groups. Both user and b - [POST /account_groups](https://docs.upvest.co/api/account-groups/create_account_group.md): Creates an account group for a user or a business. An account group aggregates the accounts within it for tax calculation and regulatory reporting purposes and holds positions in the form of cash; the - [GET /businesses/{business_id}/account_groups](https://docs.upvest.co/api/account-groups/list_business_account_groups.md): Lists the account groups of a business specified by ID. - [POST Account Group events](https://docs.upvest.co/api/account-groups/account_group_event.md): Notifies subscribers of account group lifecycle events. Triggered when an account group is created, activated, updated, locked, closed, or has its closure initiated. See the Account webhooks guide ([T ## Corporate Actions - [POST Corporate Action Events](https://docs.upvest.co/api/corporate-actions/corporate_action_event.md): Notifies tenants of corporate actions impacting securities holdings across all accounts within the organization. This webhook sends updates for dividends, stock splits, mergers, tender offers, and o ## Tax Wrappers - [POST /isa/wrappers](https://docs.upvest.co/api/tax-wrappers/create_isa_tax_wrapper.md): Creates an ISA tax wrapper for an account group, holding the business rules that apply to the tax-wrapped product. The account group must have been created with `type` set to `ISA`. For a `STOCKS_AND_ - [GET /isa/wrappers/{tax_wrapper_id}/allowances](https://docs.upvest.co/api/tax-wrappers/retrieve_isa_allowances.md): Returns the ISA allowances of the tax wrapper identified by `tax_wrapper_id`. An `ANNUAL` allowance covers one UK tax year, which runs from 6 April to 5 April and is identified in `yyyy/yyyy` form. Al - [POST ISA tax wrapper events](https://docs.upvest.co/api/tax-wrappers/isa_tax_wrappers_event.md): ISA Tax Wrappers events - [POST ISA allowance events](https://docs.upvest.co/api/tax-wrappers/isa_allowance_event.md): ISA Allowance events ## ISA Transfers - [POST /isa/transfers](https://docs.upvest.co/api/isa-transfers/create_isa_transfer.md): Creates an ISA transfer, moving all or part of an end user's existing ISA into an Upvest Stocks and Shares ISA while preserving their current-year allowance. Set `transfer_type` to `ISA_EXTERNAL` for - [POST ISA Transfers events](https://docs.upvest.co/api/isa-transfers/isa_transfer_event.md): ISA Transfers events ## Tax Exemptions - [POST /tax_exemptions](https://docs.upvest.co/api/tax-exemptions/create_tax_exemption.md): Creates a tax exemption order for end users who are resident in Germany for tax purposes. Upvest must hold the end user's Tax Identification Number before an exemption can be created. The request is p - [GET /tax_exemptions/{tax_exemption_id}](https://docs.upvest.co/api/tax-exemptions/retrieve_tax_exemption_by_id.md): Returns the tax exemption order identified by `tax_exemption_id`, including its status and the allowance used and remaining for the tax year. See the [Retrieving tax exemption orders guide](https://do - [PUT /tax_exemptions/{tax_exemption_id}](https://docs.upvest.co/api/tax-exemptions/update_tax_exemption.md): Updates the tax exemption order identified by `tax_exemption_id`. See the [Updating a tax exemption guide](https://docs.upvest.co/products/tol/guides/taxes/tax_exemptions_update) for the rules governi - [DELETE /tax_exemptions/{tax_exemption_id}](https://docs.upvest.co/api/tax-exemptions/delete_tax_exemption.md): Deletes the tax exemption order identified by `tax_exemption_id` and stops it renewing in subsequent tax years. Deletion succeeds only while none of the associated end users have claimed an exemption - [GET /users/{user_id}/tax_exemptions](https://docs.upvest.co/api/tax-exemptions/retrieve_tax_exemptions_for_user.md): Returns the tax exemption orders of the end user identified by `user_id`. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching t - [POST Tax exemption events](https://docs.upvest.co/api/tax-exemptions/tax_exemption_event.md): Tax Exemption Events - [POST Tax exemption failure events](https://docs.upvest.co/api/tax-exemptions/tax_exemption_failure_event.md): Tax Exemption Failure Events ## Tax Collections - [POST Tax collection events](https://docs.upvest.co/api/tax-collections/tax_collection_event.md): Tax Collection Events ## Instruments - [GET /instruments](https://docs.upvest.co/api/instruments/list_instruments.md): Returns the list of instruments available on the Upvest platform. Narrow the list with the `trading_status` query parameter, and page through results with `offset` and `limit`; `meta.total_count` give - [GET /instruments/{instrument_id}](https://docs.upvest.co/api/instruments/retrieve_instrument.md): Returns the instrument identified by `instrument_id`, including its identifiers, name, trading status, and whether it supports fractional investing. See the instruments guide ([TOL](https://docs.upves - [POST Instruments events](https://docs.upvest.co/api/instruments/instrument_event.md): Instruments events ## Price Data - [GET /instruments/{instrument_id}/venues](https://docs.upvest.co/api/price-data/retrieve_instrument_venues.md): The venues where the instrument is traded and for which the price data is available. - [GET /instruments/{instrument_id}/venues/{venue_id}/prices/latest](https://docs.upvest.co/api/price-data/retrieve_instrument_latest_price.md): Returns the instrument's latest price as available at the specified venue. **NOTE**: Please note that in live mode we provide the latest prices that we receive from our data provider. However, it is t - [GET /instruments/{instrument_id}/venues/{venue_id}/prices/ohlc](https://docs.upvest.co/api/price-data/retrieve_instrument_prices_ohlc.md): Returns OHLC prices for the instrument at the specified venue for the chosen time period. If requested interval is `1d`, then the response also includes days with 0 volume. In these cases `open`, `hig ## Orders - [GET /accounts/{account_id}/orders](https://docs.upvest.co/api/orders/list_account_orders.md): Returns a paginated list of orders for the account specified by its ID, including their statuses, executions, and fee configurations. See the Orders guide ([TOL](https://docs.upvest.co/products/tol/gu - [POST /orders](https://docs.upvest.co/api/orders/place_order.md): Places a new order for an instrument. After the request is accepted, the order is processed asynchronously — use the returned `id` to poll for status or subscribe to order webhook events. See the Orde - [GET /orders/{order_id}](https://docs.upvest.co/api/orders/retrieve_order.md): Returns the order specified by its ID, including its current status, executions, fee configuration, and any cancellation reason. See the Orders guide ([TOL](https://docs.upvest.co/products/tol/guides/ - [DELETE /orders/{order_id}](https://docs.upvest.co/api/orders/cancel_order.md): Cancels an order specified by its ID. It is possible to cancel an order in the `NEW` or `PROCESSING` status. Once a cancellation has been accepted, the further processing steps take place asynchronous - [GET /orders/{order_id}/executions/{execution_id}](https://docs.upvest.co/api/orders/retrieve_order_execution.md): Returns the order execution specified by its ID. An execution represents a single trade fill within an order; an order may have multiple executions if it is partially filled across several trades. See - [POST Orders events](https://docs.upvest.co/api/orders/order_event.md): Orders events - [POST Executions events](https://docs.upvest.co/api/orders/execution_event.md): Executions events - [POST Order Cancellations events](https://docs.upvest.co/api/orders/order_cancellation_event.md): Order Cancellations events ## Portfolios - [GET /portfolios/allocations](https://docs.upvest.co/api/portfolios/list_portfolios_allocations.md): Returns a paginated list of portfolio allocations for the authenticated client. Allocations define the target instrument weights that portfolio configurations use to invest and rebalance. See the Port - [POST /portfolios/allocations](https://docs.upvest.co/api/portfolios/create_portfolios_allocation.md): Creates a named portfolio allocation specifying a set of instrument weights. The `allocation` array must contain at least one instrument entry. Weights are expressed as percentages and must sum to 100 - [GET /portfolios/allocations/{allocation_id}](https://docs.upvest.co/api/portfolios/retrieve_portfolios_allocation.md): Retrieves a portfolio allocation by its ID, including its name, instrument weights, and associated rebalancing strategy IDs. See the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/ - [PUT /portfolios/allocations/{allocation_id}](https://docs.upvest.co/api/portfolios/update_portfolios_allocation.md): Updates the name and/or instrument weights of an existing portfolio allocation. Accounts with a portfolio configuration referencing this allocation will use the new weights on their next rebalancing. - [GET /portfolios/configurations](https://docs.upvest.co/api/portfolios/list_portfolios_configurations.md): Returns a paginated list of portfolio configurations for the authenticated client. Each configuration links an account to an allocation and defines which rebalancing strategies apply to that account. - [POST /portfolios/configurations](https://docs.upvest.co/api/portfolios/create_portfolios_configuration.md): Creates a portfolio configuration for an investment account, associating it with a target allocation and optional rebalancing strategies. Only one active configuration per account is permitted. See th - [GET /portfolios/configurations/{account_id}](https://docs.upvest.co/api/portfolios/retrieve_portfolios_configuration.md): Retrieves a portfolio configuration by its ID, including the linked allocation and any associated rebalancing strategies. See the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/por - [PATCH /portfolios/configurations/{account_id}](https://docs.upvest.co/api/portfolios/update_portfolios_configuration.md): Updates the allocation or rebalancing strategies of an existing portfolio configuration. See the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.up - [DELETE /portfolios/configurations/{account_id}](https://docs.upvest.co/api/portfolios/delete_portfolios_configuration.md): Delete portfolios configuration (hard delete) - [GET /portfolios/orders](https://docs.upvest.co/api/portfolios/list_portfolios_orders.md): Returns a paginated list of portfolio orders for the authenticated client. Portfolio orders represent buy or sell instructions that invest or withdraw a cash amount across all instruments in the accou - [POST /portfolios/orders](https://docs.upvest.co/api/portfolios/create_portfolios_order.md): Places a buy or sell portfolio order for the specified account, distributing the cash amount across instruments according to the account's allocation weights. One underlying instrument order is genera - [GET /portfolios/orders/{portfolio_order_id}](https://docs.upvest.co/api/portfolios/retrieve_portfolios_order.md): Retrieves a portfolio order by its ID, including the status and details of each underlying instrument order. See the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [B - [DELETE /portfolios/orders/{portfolio_order_id}](https://docs.upvest.co/api/portfolios/cancel_portfolios_order.md): Cancel portfolios order. Cancellations may not be possible - in rare situations, some individual orders within portfolios order may already have been filled. In this case, cancellation could result in - [GET /portfolios/allocations/{allocation_id}/accounts](https://docs.upvest.co/api/portfolios/list_portfolios_allocation_accounts.md): Returns a paginated list of accounts associated with a specific portfolio allocation. See the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upves - [POST Portfolio orders events](https://docs.upvest.co/api/portfolios/portfolio_order_event.md): Fires when a portfolio order transitions to a new status (`PORTFOLIO_ORDER.NEW`, `PORTFOLIO_ORDER.PROCESSING`, `PORTFOLIO_ORDER.FILLED`, `PORTFOLIO_ORDER.SETTLED`, `PORTFOLIO_ORDER.CANCELLED`). - [POST Portfolio allocations events](https://docs.upvest.co/api/portfolios/portfolio_allocation_event.md): Fires when a portfolio allocation is created or updated (`PORTFOLIO_ALLOCATION.CREATED`, `PORTFOLIO_ALLOCATION.CHANGED`). ## Portfolios Rebalancing - [POST /portfolios/rebalancings/executions](https://docs.upvest.co/api/portfolios-rebalancing/trigger_portfolio_rebalancing.md): Triggers an immediate rebalancing execution for all accounts linked to the specified allocation. The rebalancing adjusts each account's positions to match the current target allocation weights. In rar - [GET /portfolios/rebalancings/executions/{execution_id}](https://docs.upvest.co/api/portfolios-rebalancing/retrieve_portfolios_rebalancing_execution.md): Retrieve portfolios rebalancing execution - [GET /portfolios/rebalancings/executions/{execution_id}/orders](https://docs.upvest.co/api/portfolios-rebalancing/list_portfolio_rebalancing_execution_orders.md): List portfolio rebalancing execution orders - [POST Portfolio rebalancing execution orders events](https://docs.upvest.co/api/portfolios-rebalancing/portfolio_rebalancing_execution_order_event.md): Portfolio rebalancing execution orders events ## Savings Plans - [GET /savings_plans/{savings_plan_id}](https://docs.upvest.co/api/savings-plans/retrieve_savings_plan.md): Retrieve a savings plan specified by its ID. - [DELETE /savings_plans/{savings_plan_id}](https://docs.upvest.co/api/savings-plans/delete_savings_plan.md): Delete a savings plan specified by its ID. - [GET /savings_plans](https://docs.upvest.co/api/savings-plans/list_savings_plans.md): Returns a paginated list of savings plans for the authenticated client. Savings plans can be of type `INSTRUMENT` (recurring buy of a single instrument) or `PORTFOLIO` (recurring investment distribute - [POST /savings_plans](https://docs.upvest.co/api/savings-plans/create_savings_plan.md): Creates a recurring savings plan that automatically invests a fixed cash amount at a defined frequency. Set `type` to `INSTRUMENT` to invest in a single instrument, or `PORTFOLIO` to distribute the in - [GET /savings_plans/{savings_plan_id}/executions/{savings_plan_execution_id}](https://docs.upvest.co/api/savings-plans/retrieve_savings_plan_execution.md): Retrieves a single execution of a savings plan by its ID, including the order placed and its current status. - [DELETE /savings_plans/{savings_plan_id}/executions/{savings_plan_execution_id}](https://docs.upvest.co/api/savings-plans/delete_savings_plan_execution.md): Deletes a scheduled savings plan execution before it has been processed. Only executions in the `NEW` status can be deleted. - [GET /savings_plans/{savings_plan_id}/executions](https://docs.upvest.co/api/savings-plans/list_savings_plan_executions.md): List savings plan executions for a saving plan specified by its ID. - [POST Savings plan execution events](https://docs.upvest.co/api/savings-plans/savings_plan_execution_event.md): Fires when a savings plan execution changes status (`SAVINGS_PLAN_EXECUTION.NEW`, `SAVINGS_PLAN_EXECUTION.PROCESSING`, `SAVINGS_PLAN_EXECUTION.FILLED`, `SAVINGS_PLAN_EXECUTION.SETTLED`, `SAVINGS_PLAN_ - [POST Savings plan events](https://docs.upvest.co/api/savings-plans/savings_plan_event.md): Fires when a savings plan is created or cancelled (`SAVINGS_PLAN.CREATED`, `SAVINGS_PLAN.CANCELLED`). ## Liquidations - [GET /accounts/{account_id}/liquidations](https://docs.upvest.co/api/liquidations/list_accounts_liquidations.md): Returns a paginated list of account liquidation requests for the authenticated client. See the Liquidations guide ([TOL](https://docs.upvest.co/products/tol/guides/liquidations) / [BYOL](https://docs. - [POST /accounts/{account_id}/liquidations](https://docs.upvest.co/api/liquidations/create_account_liquidation.md): Initiates a full liquidation of an investment account, placing sell orders for all held positions and converting the proceeds to cash. Exactly one of `user_id` or `business_id` must be provided in the - [GET /accounts/{account_id}/liquidations/{account_liquidation_id}](https://docs.upvest.co/api/liquidations/retrieve_account_liquidation.md): Retrieves an account liquidation by its ID, including the status of each individual sell order. See the Liquidations guide ([TOL](https://docs.upvest.co/products/tol/guides/liquidations) / [BYOL](http - [DELETE /accounts/{account_id}/liquidations/{account_liquidation_id}](https://docs.upvest.co/api/liquidations/cancel_account_liquidation.md): Cancels a pending account liquidation. Only liquidations in the `NEW` status can be cancelled. See the Liquidations guide ([TOL](https://docs.upvest.co/products/tol/guides/liquidations) / [BYOL](https - [POST Account liquidation events](https://docs.upvest.co/api/liquidations/account_liquidation_event.md): Fires when an account liquidation changes status (`ACCOUNT_LIQUIDATION.NEW`, `ACCOUNT_LIQUIDATION.PROCESSING`, `ACCOUNT_LIQUIDATION.FILLED`, `ACCOUNT_LIQUIDATION.CANCELLED`, `ACCOUNT_LIQUIDATION.SETTL ## Direct Debits - [GET /account_groups/{account_group_id}/payments/direct_debits](https://docs.upvest.co/api/direct-debits/list_direct_debits.md): Returns a paginated list of direct debits for the account group specified by its ID. - [POST /payments/direct_debits](https://docs.upvest.co/api/direct-debits/create_direct_debit.md): Trigger a direct debit. **Deprecation notice:** The `user_id` field is deprecated, optional, and will be removed in a future version. For business account direct debits, ownership is determined by the - [GET /payments/direct_debits/{direct_debit_id}](https://docs.upvest.co/api/direct-debits/retrieve_direct_debit.md): Returns the direct debit specified by its ID, including its current status, cash amount, mandate reference, and any cancellation reason. - [POST Direct Debit events](https://docs.upvest.co/api/direct-debits/direct_debit_event.md): Webhook callback payload for direct debit lifecycle events. Delivered when a direct debit transitions to `DIRECT_DEBIT.NEW`, `DIRECT_DEBIT.PROCESSING`, `DIRECT_DEBIT.CONFIRMED`, or `DIRECT_DEBIT.CANCE ## Top-ups - [GET /account_groups/{account_group_id}/payments/topups](https://docs.upvest.co/api/top-ups/list_topups.md): Returns a list of top-ups. - [POST /payments/topups](https://docs.upvest.co/api/top-ups/create_topup.md): Creates a top-up request for an account group and returns a `settlement_reference`. The end user must then send a SEPA Credit Transfer including that reference to complete the funding. - [GET /payments/topups/{topup_id}](https://docs.upvest.co/api/top-ups/retrieve_topup.md): Returns a top-up specified by its ID. - [DELETE /payments/topups/{topup_id}](https://docs.upvest.co/api/top-ups/cancel_topup.md): Cancels a top-up specified by its ID. It is only possible to cancel a top-up if it has the status `CONFIRMED`. - [POST Top-up events](https://docs.upvest.co/api/top-ups/topup_event.md): Webhook callback payload for top-up lifecycle events. Delivered when a top-up transitions to `TOPUP.CONFIRMED`, `TOPUP.SETTLED`, or `TOPUP.CANCELLED`. ## Withdrawals - [POST /payments/withdrawals](https://docs.upvest.co/api/withdrawals/create_cash_withdrawal.md): Trigger a withdrawal. **Deprecation notice:** The `user_id` field is deprecated, optional, and will be removed in a future version. For business account withdrawals, ownership is determined by the ref - [GET /payments/withdrawals/{withdrawal_id}](https://docs.upvest.co/api/withdrawals/retrieve_cash_withdrawal.md): Returns the cash withdrawal specified by its ID, including its current status, amount, and reference account. - [DELETE /payments/withdrawals/{withdrawal_id}](https://docs.upvest.co/api/withdrawals/cancel_cash_withdrawal.md): Cancels a withdrawal specified by its ID. It is only possible to cancel a withdrawal if it has the status `NEW`. - [GET /account_groups/{account_group_id}/payments/withdrawals](https://docs.upvest.co/api/withdrawals/list_cash_withdrawals.md): Returns a paginated list of cash withdrawals for the account group specified by its ID. - [POST Withdrawals events](https://docs.upvest.co/api/withdrawals/withdrawal_event.md): Webhook callback payload for cash withdrawal lifecycle events. Delivered when a withdrawal transitions to `WITHDRAWAL.NEW`, `WITHDRAWAL.PROCESSING`, `WITHDRAWAL.CONFIRMED`, or `WITHDRAWAL.CANCELLED`. ## Cash Balance Transfers - [GET /payments/cash_balance_transfers](https://docs.upvest.co/api/cash-balance-transfers/list_cash_balance_transfers.md): Returns a paginated list of all cash balance transfers initiated by the client, across all account groups and users. - [POST /payments/cash_balance_transfers](https://docs.upvest.co/api/cash-balance-transfers/create_cash_balance_transfer.md): Create an internal cash balance transfer between two account groups belonging to the same user and tenant. The cash leaves the source account group and arrives at the target account group as a single - [GET /payments/cash_balance_transfers/{cash_balance_transfer_id}](https://docs.upvest.co/api/cash-balance-transfers/retrieve_cash_balance_transfer.md): Retrieve a cash balance transfer by its ID. - [DELETE /payments/cash_balance_transfers/{cash_balance_transfer_id}](https://docs.upvest.co/api/cash-balance-transfers/cancel_cash_balance_transfer.md): Cancels a cash balance transfer specified by its ID. It is only possible to cancel a transfer while it has the status `ISSUED`. - [GET /users/{user_id}/payments/cash_balance_transfers](https://docs.upvest.co/api/cash-balance-transfers/list_user_cash_balance_transfers.md): Returns the list of cash balance transfers of a user specified by ID. - [GET /businesses/{business_id}/payments/cash_balance_transfers](https://docs.upvest.co/api/cash-balance-transfers/list_business_cash_balance_transfers.md): Returns the list of cash balance transfers of a business specified by ID. - [POST Cash Balance Transfers events](https://docs.upvest.co/api/cash-balance-transfers/cash_balance_transfer_event.md): Webhook callback payload for cash balance transfer lifecycle events. Delivered when a transfer transitions to `CASH_BALANCE_TRANSFER.ISSUED`, `CASH_BALANCE_TRANSFER.CONFIRMED`, or `CASH_BALANCE_TRANSF ## Reference Accounts - [GET /users/{user_id}/payments/reference_accounts](https://docs.upvest.co/api/reference-accounts/list_reference_accounts.md): Returns the list of reference accounts of a user specified by ID. - [POST /payments/reference_accounts](https://docs.upvest.co/api/reference-accounts/create_reference_account.md): Creates a new reference account for a user or business specified by ID. - [GET /payments/reference_accounts/{reference_account_id}](https://docs.upvest.co/api/reference-accounts/retrieve_reference_account.md): Retrieves the reference account specified by its ID. - [DELETE /payments/reference_accounts/{reference_account_id}](https://docs.upvest.co/api/reference-accounts/delete_reference_account.md): Deletes the reference account specified by its ID. - [GET /businesses/{business_id}/payments/reference_accounts](https://docs.upvest.co/api/reference-accounts/list_business_reference_accounts.md): Returns the list of reference accounts for a business specified by ID. ## Mandates - [GET /users/{user_id}/payments/mandates](https://docs.upvest.co/api/mandates/list_mandates.md): Returns a paginated list of direct debit mandates for the user specified by their ID. - [GET /businesses/{business_id}/payments/mandates](https://docs.upvest.co/api/mandates/list_business_mandates.md): Returns a paginated list of direct debit mandates for the business specified by its ID. - [POST /payments/mandates](https://docs.upvest.co/api/mandates/create_mandate.md): Create a mandate. Supports both user and business accounts. Provide `user_id` for user flows or `business_id` for business flows — exactly one must be specified. - [GET /payments/mandates/{mandate_id}](https://docs.upvest.co/api/mandates/retrieve_mandate.md): Retrieve a direct debit mandate. The response contains either `user_id` or `business_id` depending on whether the mandate belongs to a user or business account. - [DELETE /payments/mandates/{mandate_id}](https://docs.upvest.co/api/mandates/delete_mandate.md): Deletes the direct debit mandate specified by its ID. Deletion permanently removes the mandate; associated direct debits already in progress are not affected. ## Virtual Bank Accounts - [GET /account_groups/{account_group_id}/payments/virtual_bank_accounts](https://docs.upvest.co/api/virtual-bank-accounts/list_virtual_bank_accounts.md): Returns a list of virtual bank accounts. - [POST /payments/virtual_bank_accounts](https://docs.upvest.co/api/virtual-bank-accounts/create_virtual_bank_account.md): Creates a virtual bank account for an account group. The virtual bank account provides an IBAN and BIC that end users can use to send SEPA Credit Transfers directly to their investment account. - [GET /payments/virtual_bank_accounts/{virtual_bank_account_id}](https://docs.upvest.co/api/virtual-bank-accounts/retrieve_virtual_bank_account.md): Returns a virtual bank account specified by its ID. - [POST Virtual Bank Accounts events](https://docs.upvest.co/api/virtual-bank-accounts/virtual_bank_account_event.md): Webhook callback payload for virtual bank account creation events (`VIRTUAL_BANK_ACCOUNT.CREATED`). ## Credit Fundings - [GET /account_groups/{account_group_id}/payments/credit_funding_details](https://docs.upvest.co/api/credit-fundings/retrieve_funding_details.md): Returns the virtual bank account details needed to fund an account group via SEPA Credit Transfer. Clients should present these details to end users so they can initiate the bank transfer. - [GET /account_groups/{account_group_id}/payments/credit_fundings](https://docs.upvest.co/api/credit-fundings/list_credit_fundings.md): Returns a paginated list of credit fundings for the account group specified by its ID. A credit funding represents an incoming SEPA Credit Transfer that has been received and applied to the account gr - [GET /payments/credit_fundings/{credit_funding_id}](https://docs.upvest.co/api/credit-fundings/retrieve_credit_funding.md): Returns the credit funding specified by its ID, including its status, cash amount, and counterparty details. - [POST Credit Funding events](https://docs.upvest.co/api/credit-fundings/credit_funding_event.md): Webhook callback payload for credit funding events. Delivered when an incoming SEPA Credit Transfer transitions to `CREDIT_FUNDING.CONFIRMED` or `CREDIT_FUNDING.CANCELLED`. ## Cash Balances - [GET /account_groups/{account_group_id}/payments/cash_balances](https://docs.upvest.co/api/cash-balances/retrieve_cash_balances.md): Returns the list of cash balances held by the account group. See the Cash balances guide ([TOL](https://docs.upvest.co/products/tol/guides/payments/cash_balances/cash_balances_intro) / [BYOL](https:// - [GET /account_groups/{account_group_id}/payments/cash_balances/{currency}](https://docs.upvest.co/api/cash-balances/retrieve_cash_balance_with_currency.md): Returns the account group's cash balance for the given `currency`. See the Cash balances guide ([TOL](https://docs.upvest.co/products/tol/guides/payments/cash_balances/cash_balances_retrieving) / [BYO - [GET /account_groups/{account_group_id}/payments/cash_balance](https://docs.upvest.co/api/cash-balances/retrieve_cash_balance.md): **Deprecated.** Use `GET /account_groups/{account_group_id}/payments/cash_balances/{currency}` instead. Returns the account group's cash balance. - [POST Cash Balance events](https://docs.upvest.co/api/cash-balances/cash_balance_event.md): Cash Balance events ## Positions - [GET /accounts/{account_id}/positions](https://docs.upvest.co/api/positions/list_positions.md): Returns the list of positions held by the account. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching positions. See the Posit - [GET /accounts/{account_id}/positions/{instrument_id}](https://docs.upvest.co/api/positions/retrieve_position.md): Returns the account's position in the given instrument. See the Positions guide ([TOL](https://docs.upvest.co/products/tol/guides/positions/interpreting_positions) / [BYOL](https://docs.upvest.co/prod - [POST Positions events](https://docs.upvest.co/api/positions/position_event.md): Positions events ## Valuations - [GET /accounts/{account_id}/valuations/current](https://docs.upvest.co/api/valuations/get_account_valuation.md): Returns the account's current valuation, calculated from its current positions and the requested `price_quality`. See the Account valuations guide ([TOL](https://docs.upvest.co/products/tol/guides/pos - [GET /accounts/{account_id}/valuations](https://docs.upvest.co/api/valuations/list_account_valuation_history.md): Returns the account's historical end-of-day valuations. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching valuations. See the - [POST Account valuation events](https://docs.upvest.co/api/valuations/account_valuation_event.md): Account valuation events - [POST Intraday account valuation events](https://docs.upvest.co/api/valuations/intraday_account_valuation_event.md): Intraday account valuation events ## Returns - [GET /accounts/{account_id}/returns](https://docs.upvest.co/api/returns/list_account_returns.md): Returns the account's daily time-weighted return (TWR), which measures investment performance independently of deposits, withdrawals, and other external cash flows. Use the `offset` and `limit` query - [POST Account returns events](https://docs.upvest.co/api/returns/account_returns_event.md): Account returns event ## Virtual Cash Balances - [POST /virtual_cash_balances/increases](https://docs.upvest.co/api/virtual-cash-balances/create_virtual_cash_increase.md): Increases an account group's virtual cash balance, making the specified `amount` available for trading before the corresponding real cash has settled. Requires the `Idempotency-Key` header to prevent - [POST /virtual_cash_balances/decreases](https://docs.upvest.co/api/virtual-cash-balances/create_virtual_cash_decrease.md): Decreases an account group's virtual cash balance, for example after an order has settled or before a withdrawal. If the account group does not yet have sufficient real cash, the decrease is queued wi - [DELETE /virtual_cash_balances/decreases/{virtual_cash_decrease_id}](https://docs.upvest.co/api/virtual-cash-balances/cancel_virtual_cash_decrease.md): Cancels a virtual cash decrease specified by its ID. It is only possible to cancel a virtual cash decrease if it has the status `ISSUED` or `QUEUED`. - [POST Virtual cash increase events](https://docs.upvest.co/api/virtual-cash-balances/virtual_cash_increase_event.md): Virtual cash increase events - [POST Virtual cash decrease events](https://docs.upvest.co/api/virtual-cash-balances/virtual_cash_decrease_event.md): Virtual cash decrease events ## Fees - [GET /fees/collections](https://docs.upvest.co/api/fees/list_fee_collections.md): Returns the list of fee collections. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching fee collections. Narrow the result set - [POST /fees/collections](https://docs.upvest.co/api/fees/create_fee_collection.md): Creates a fee collection for a fee amount you have already calculated. The account must not be in `PENDING_APPROVAL` or `CLOSED` status; a request against an account in either status is rejected with - [GET /fees/collections/{fee_collection_id}](https://docs.upvest.co/api/fees/retrieve_fee_collection.md): Returns the fee collection identified by `fee_collection_id`, including its status and the amount processed so far. A fee collection moves through `PROCESSING`, then either `FINALISED` once the fees h - [POST Fee collection events](https://docs.upvest.co/api/fees/fee_collection_event.md): Fee collection events ## Fees Configurations - [POST /fees/configurations](https://docs.upvest.co/api/fees-configurations/create_fee_configuration.md): Assigns a fee model to an account so that fees are calculated for that account. Fee models are set up by Upvest from your requirements and identified by the `fee_model_id` Upvest provides. Every accou - [GET /fees/configurations/{account_id}](https://docs.upvest.co/api/fees-configurations/retrieve_fee_configurations.md): Returns the fee configuration of the account identified by `account_id`. See the Fee model and configuration guide ([TOL](https://docs.upvest.co/products/tol/guides/fees/fees_model_configuration) / [B - [PATCH /fees/configurations/{account_id}](https://docs.upvest.co/api/fees-configurations/update_fee_configuration.md): Updates the fee configuration of the account identified by `account_id`. Only the last fee configuration submitted on a given day is used to calculate that day's fees. See the Fee model and configurat ## Transaction Fees Models - [GET /transaction_fees/models](https://docs.upvest.co/api/transaction-fees-models/list_transaction_fee_models.md): Returns a paginated list of the transaction fee models created for your client account. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number - [POST /transaction_fees/models](https://docs.upvest.co/api/transaction-fees-models/create_transaction_fee_model.md): Creates a transaction fee model that defines how per-order transaction fees are calculated — either as fixed cash amounts (`ABSOLUTE`) or in basis points of the order value (`RELATIVE`), with one or m - [GET /transaction_fees/models/{transaction_fee_model_id}](https://docs.upvest.co/api/transaction-fees-models/retrieve_transaction_fee_model.md): Returns the transaction fee model with the given ID, including its currency, charge method, value type, and tier structure. See the Transaction fees guide ([TOL](https://docs.upvest.co/products/tol/gu ## Reports - [GET /users/{user_id}/reports](https://docs.upvest.co/api/reports/list_user_reports.md): Returns the list of reports generated for the end user identified by `user_id`. Narrow the list with the `type`, `instrument`, `start_date`, and `end_date` query parameters, and page through results w - [POST /reports](https://docs.upvest.co/api/reports/create_report.md): Creates a report from data the client submits, for either an end user or a business. This is how clients supply the planned fee structure and order details that Upvest needs to produce a compliant MiF - [GET /reports/{report_id}](https://docs.upvest.co/api/reports/retrieve_report.md): Retrieve a report for either a natural person or a business entity. - [GET /businesses/{business_id}/reports](https://docs.upvest.co/api/reports/list_business_reports.md): Returns a paginated list of reports generated for the business identified by `business_id`. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total nu - [POST Reports events](https://docs.upvest.co/api/reports/report_event.md): Report events for either a natural person or a business entity. ## Treasury Reports - [POST Treasury reports events](https://docs.upvest.co/api/treasury-reports/treasury_report_event.md): Treasury reports events. `TREASURY_REPORT.CREATED` is emitted when a treasury settlement report has been generated. `TREASURY_REPORT.CONFIRMED` is emitted once the treasury operation covered by the re ## Transactions - [GET /transactions/cash](https://docs.upvest.co/api/transactions/list_cash_transactions.md): Returns the list of cash transactions for an account group. Cash movements are recorded at account group level, so this endpoint is filtered by `account_group_id` rather than by account. Restrict the - [GET /transactions/securities](https://docs.upvest.co/api/transactions/list_securities_transactions.md): Returns the list of securities transactions for an account group or a single account. Securities movements are recorded at account level, so this endpoint accepts both `account_group_id` and `account_ - [POST Cash transactions events](https://docs.upvest.co/api/transactions/cash_transaction_event.md): Cash transactions events - [POST Security transactions events](https://docs.upvest.co/api/transactions/security_transaction_event.md): Security transactions events ## Files - [GET /files/{folder}/{file_name}](https://docs.upvest.co/api/files/fetching_file_metadata.md): Returns the metadata of the file identified by `folder` and `file_name`, together with a signed URL for downloading it. Downloading a file is a two-step process: request the metadata here, then fetch ## Securities Transfers - [GET /securities_transfers](https://docs.upvest.co/api/securities-transfers/list_securities_transfers.md): Returns the list of securities transfers. Restrict the list to one direction with the `direction` query parameter, and page through results with the `offset` and `limit` query parameters; `meta.total_ - [POST /securities_transfers](https://docs.upvest.co/api/securities-transfers/create_securities_transfer.md): Creates a securities transfer, moving a position in a single instrument between an Upvest account and an external custodian. Set `direction` to `INCOMING` to move securities into an Upvest account, or - [POST Securities Transfers events](https://docs.upvest.co/api/securities-transfers/securities_transfer_event.md): Securities Transfers events ## Webhook Subscriptions - [GET /auth/verify_keys](https://docs.upvest.co/api/webhook-subscriptions/get_jwks.md): Returns the set of public keys used to verify the signatures on webhook payloads, as a JSON Web Key Set. Verify the signature of every webhook you receive against these keys before acting on it. Keys - [GET /webhooks](https://docs.upvest.co/api/webhook-subscriptions/list_webhooks.md): Returns the list of webhook subscriptions. Use the `offset` and `limit` query parameters to page through results; `meta.total_count` gives the total number of matching subscriptions. See the implement - [POST /webhooks](https://docs.upvest.co/api/webhook-subscriptions/create_webhook.md): Creates a webhook subscription, registering a URL that the Investment API calls when the events you select occur. The URL must use HTTPS, resolve to a DNS name rather than an IP address, serve TLS 1.2 - [GET /webhooks/{webhook_id}](https://docs.upvest.co/api/webhook-subscriptions/retrieve_webhook.md): Returns the webhook subscription identified by `webhook_id`, including the URL it calls, the event types it covers, and whether it is enabled. See the implementing webhooks guide ([TOL](https://docs.u - [DELETE /webhooks/{webhook_id}](https://docs.upvest.co/api/webhook-subscriptions/delete_webhook.md): Deletes the webhook subscription identified by `webhook_id`, stopping all further deliveries to its URL. See the implementing webhooks guide ([TOL](https://docs.upvest.co/products/tol/getting_started/ - [PATCH /webhooks/{webhook_id}](https://docs.upvest.co/api/webhook-subscriptions/update_webhook.md): Updates the webhook subscription identified by `webhook_id`. Use this to change the callback URL, adjust which event types are delivered, or enable and disable delivery without deleting the subscripti - [POST /webhooks/{webhook_id}/test](https://docs.upvest.co/api/webhook-subscriptions/test_webhook.md): Sends test event data to the URL of the webhook subscription identified by `webhook_id`, so you can confirm your handler is reachable and responding correctly. The response reports what your endpoint ## Tests - [POST /tests/payments/transactions](https://docs.upvest.co/api/tests/create_bank_transaction.md): Trigger a bank transaction for testing purposes. This can be used to simulate a money transfer for various flows which need cash settlements on one of our bank accounts.