Enabling portfolio investments

This guide will walk you through the implementation steps necessary to offer portfolio products to your users, how users can invest in the portfolios and how you can manage these portfolio investments.

Placing the first portfolio order

1. Creating a portfolio allocation

Prerequisite

Before your users can invest in a portfolio of selected instruments, the target allocation of the respective portfolio must be defined. This is typically a step in which a portfolio manager (or the asset management department) selects the most suitable instruments - and their respective weightings. In this way, the investor's 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, you can create them at any time. This resource reflects the target state of a portfolio investment and is - if desired - reusable across the entire user base on your platform. In the traditional world, this is more commonly referred to as a 'model portfolio'.

Portfolio allocation specification

A portfolio allocation is defined by a list of instruments and their respective portfolio weights as a percentage of the total investment. They have the following specifications:

• The sum of the weights of all instruments in the allocation must equal 1.
• Each individual weight must be greater than 0 (i.e., no short positions are allowed).
• A portfolio allocation must include at least one instrument and no instrument can be listed twice.
• You can 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.

Example response

{
  "id": "436244bb-4afd-4002-b53b-b1d7a3bca032",
  "created_at": "2021-07-21T14:10:00.00Z",
  "updated_at": "2021-07-21T14:10:00.00Z",
  "name": "Allocation 1",
  "allocation": [
    {
      "instrument_id": "IE00B0M62Q58",
      "instrument_id_type": "ISIN",
      "weight": "0.7"
    },
    {
      "instrument_id": "US0378331005",
      "instrument_id_type": "ISIN",
      "weight": "0.3"
    }
  ]
}

As soon as a new portfolio allocation has been created, you will receive a webhook confirming the creation.

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 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.

1. Listing portfolio allocations

You can list all created portfolio allocations as follows:

GET /portfolios/allocations

To get a more selective overview of portfolio allocations, query the list endpoint using the following parameters:

instrument_ids | Filters the list to show only portfolio allocations that contain the specified instruments. instrument_ids can have either the format ISIN or UUID.| start_date | Filters the list to show only portfolio allocations created as of this date.
You can combine start_date and end_date to filter by a range of dates. | end_date | Filters the list to show only portfolio allocations that were created up to this date.
You can combine start_date and end_date to filter by a range of dates.|

2. Listing a portfolio allocation by ID

You can retrieve a single allocation by referencing its allocation_id:

GET /portfolios/allocations/{allocation_id}.

3. Changing a portfolio allocation

The Investment API provides flexibility in customising initial portfolio allocations.

With the following API call, 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 react to changing market conditions, investor preferences, and new information at any time:

PUT /portfolios/allocations/{allocation_id}

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"
        }
    ]
}

The example call results in the following changes to the portfolio allocation:

• The weight of the first instrument is reduced from 0.7 to 0.5
• A third instrument is added to the allocation using an Upvest UUID as instrument identifier (i.e. for a cryptocurrency).

Once 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; this step only defines the new target state. The actual reallocation takes place after a rebalancing of the user's account is triggered. 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 the portfolio configuration of the account by replacing the existing allocation with the new one.

PATCH portfolios/configurations/{account_id}

Example request

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

In this sample request, a new target portfolio allocation is set 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 complete rebalancing of the portfolio, you can trigger a rebalancing for that account:

POST /portfolios/rebalancings/executions.

Example request

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

For more information on triggering a rebalancing, see the respective guide.

What's next?

Now you can offer portfolio products to your users and know how to manage them. As a next step, we recommend you look at the mechanics of a portfolio order before exploring how to trigger a rebalancing.