Enabling portfolio investments

This guide walks you through the implementation steps necessary to start offering portfolio products to your users, how users can invest into the portfolios, and how you can manage these portfolio investments.

Placing the first portfolio order

1 Creating a portfolio allocation

Before your users can invest in a portfolio of selected instruments, the target allocation of the particular portfolio must be defined. This is typically a step in which a portfolio manager (or the asset management department) selects the most appropriate instruments - and their respective weights. This way, investors preferences can be best reflected in the resulting portfolio investment.
In the Investment API, this step is performed by creating a portfolio allocation resource. Portfolio allocations are standalone resources, and can be created at any time. This resource reflects the target state of a portfolio investment, and - if desired - is reusable across the whole user base on your platform. In the traditional world, this is more commonly referred to as a “model portfolio”.

A portfolio allocation is defined by a list of instruments and their respective portfolio weights as a percentage share of total investment. The aggregated weights of all instruments in the allocation must sum up to 1, and each individual weight must be greater than zero (i.e., no short positions are allowed). A portfolio allocation must contain at least 1 instrument, and no instrument can be listed twice. Lastly, you may only include instruments that are tradable on the Investment API.

To create a portfolio allocation, send the following request:

POST /portfolios/allocations

Example request

{
    "name": "Allocation 1",
    "allocation": [
        {
            "instrument_id": "IE00BOM62058",
            "instrument_id_type": "ISIN",
            "weight": "0.7"
        },
        {
            "instrument_id": "US0378331005",
            "instrument_id_type": "ISIN",
            "weight": "0.3"
        }
    ]
}

This example request creates a new portfolio allocation containing two different instruments and returns a corresponding allocation_id. Naming the created allocation is optional.

You can use the returned allocation_id to continuously manage the created portfolio allocation and to configure a portfolio investment for your users (see next step). You will receive a webhook confirming that a new portfolio allocation has been created.

2 Setting up a portfolio configuration

Prerequisite

Before you can start configuring portfolios for your users, you must create portfolio accounts for them.

To set up a portfolio configuration for an account, you only need to specify the portfolio allocation in which the user wants to invest. Specifying the portfolio allocation for an account is required to ensure that the money in that account is invested and managed according to the defined allocation. In this sense, the portfolio configuration defines the target state of the user's investment in this account.

To configure a portfolio for a user, send the following request:

POST /portfolios/configurations

Example request

{
  "account_id": "eb5ba93f-5dfe-4bf1-8571-4dadcaacc80c",
  "allocation_id": "24c230eb-5d4f-4462-9af8-6612e7bd3afg"
}

This sample request configures a portfolio investment for an account. Essentially, the portfolio configuration establishes a link between the account and the allocation. The response returns the account_id for which the portfolio was configured, since the account represents the entity through which a user's portfolio investment is managed. You can use this ID to manage a user's portfolio configuration at a later time.

3 Placing an order

Prerequisite

Before a user can start investing money, the account must be funded and in "ACTIVE" status, which means that all checks have been passed.

Once a configuration is created for an active account, the user can make an investment. Placing a portfolio order follows our standard order approach. However, instead of calculating the order volume for each individual instrument, you only need to specify the desired investment amount to place a portfolio order. The Investment API handles the conversion to individual orders in the background based on the instrument weight specified in the portfolio allocation.

To place a portfolio order, send the following request:

POST /portfolios/orders

Example request

{
  "user_id": "4b9732bd-7496-491-8a5f-6360479d7fed",
  "account id": "00ef0be8-d564-43af-b3c7-11b7a2188030",
  "cash_amount": "100.00",
  "currency" : "EUR",
  "side": "BUY"
}

In the example request, a user has placed a portfolio order for 100€. Furthermore, the request returns a portfolio_order_id which allows you to transparently track the progress of a portfolio order in its entirety. You can find more details about this process in the guide "Understanding portfolio orders".

This concludes the step-by-step process of how to enable portfolio investments to your users from scratch. Now you have all the knowledge you need to start integrating the portfolio functionality into your application.

Managing portfolio allocations

As you have seen, enabling portfolio investments with our Investment API can be very simple, requiring only a couple of API calls from initial setup to the first investment for your users. Of course, the ongoing operation and maintenance of portfolio investments does not stop there. In this chapter, we list some common use cases required to confidently run a large number of portfolio investments for your users.

Listing portfolio allocations

To list all created portfolio allocations, send GET /portfolios/allocations.

You can query the list endpoint using the following parameters to get a more selective overview of portfolio allocations that you or your users created:

Query parameter	Description
instrument_ids	Filtes the list to only show portfolio allocations that contain the specified instruments. Instrument ids can either be of the format ISIN or UUID.
start_date	Filters the list to only show portfolio allocations created from this date onwards.
end_date	Filters the list to only show portfolio allocations that were created up until this date. Start_date and end_date can be combined to filter for a range of dates.

You can also retrieve a single allocation by referencing its allocation_id. Send GET /portfolios/allocations/{allocation_id}.

Changing portfolio allocations

Our Investment API provides flexibility in customizing initial portfolio allocations.

You can add, replace, or remove individual instruments, adjust respective target weights, or modify the naming of the allocation. This allows you and your users, to respond to changing market conditions, investor preferences, and new information at any time.

When updating this resource via API, send a PUT request to update the respective portfolio allocation. Please note that the "allocation" array included in this PUT request must always contain the complete new allocation and thus fully represents the new target state (i.e., no delta updates).

For example, consider placing the following request PUT /portfolios/allocations/{allocation_id} on the allocation that we created before:

Example request

{
    "name": "Allocation 1",
    "allocation":
        {
            "instrument_id": "IE00BOM62Q58",
            "instrument_id_type": "ISIN",
            "weight": "0.5"
        },
        {
            "instrument_id": "US0378331005",
            "instrument_id_type": "ISIN",
            "weight": "0.3"
        },
        {
            "instrument_id": "6d7d7d64-e174-4b6b-84e0-306¢96382166",
            "instrument_id_type": "UPVEST",
            "weight": "0.2"
        }
    ]
}

This call would result in the following changes to the portfolio allocation:

1. We reduced the weight of the first instrument from 0.7 to 0.5
2. We added a third instrument to the allocation using a Upvest UUID as instrument identifier (i.e. for a cryptocurrency).

Whenever a portfolio allocation is successfully updated, you will receive a webhook notifying you about the change.

Switching portfolio allocations ("reallocation")

A portfolio switch entails a reallocation of the invested capital from one predefined portfolio target allocation to another. Using the Investment API, this can be done in two steps:

1. Changing the allocation in the portfolio configuration of the account
2. Triggering a rebalancing of this specific account to reach its new target allocation.

Your user's investments are not affected by step 1 alone. Step 1 only defines the new target state. The actual reallocation takes place after triggering a rebalancing of the user's account. Once the rebalancing is triggered, the underlying process ensures that only the net differences within a user's account are sold and rebalanced. This has the advantage that users do not suffer any adverse tax implications resulting from liquidating the entire portfolio and purchasing a new allocation. It also eliminates the need to close the user's account.

1 Changing the allocation

To change the allocation, you need to adjust that account's portfolio configuration by replacing the existing allocation with the new one. For example, consider the following request: PATCH /portfolios/configurations/{account_id}

Example request

{
    "allocation_id": "359d7d64-e174-4b6b-84e0-306v963fc16f"
}

This example request sets a new target portfolio allocation for the user's account. From now on, the user's investments in this account will be managed according to the new allocation.

2 Triggering a rebalancing

To finish the portfolio switch, you can trigger a rebalancing for that account using the POST /portfolios/rebalancings/executions.

Example request

{
  "accounts": [
    "eb5ba93f-5dfe-4bf1-8571-4daacaacc80c"
  ]
}

More on triggering a rebalancing can be found in the respective guide.

What's next?

Now you can start offering portfolio products to your users and know how to manage them. As a next step, we recommend to dive deeper into the mechanics of a portfolio order before exploring how to trigger a rebalancing.