Creating Portfolio Allocations

Before your users can invest in a portfolio of selected instruments, the target allocation of the portfolio must be defined. A portfolio manager (or the asset management department) will select the most suitable instruments and their weightings. In this way, the investor's preferences are reflected in the resulting portfolio investment. Outside the Upvest Investment API this is sometimes called a 'model portfolio'.

In the Investment API, this step is performed by creating a portfolio allocation resource. Portfolio allocations are standalone resources that you can create at any time. This resource reflects the target state of a portfolio investment and may be reused across the entire user base on your platform.

→ 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 ahere to the following rules:

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

Parameter	Description
`id`	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).
`name`	Optional: Naming the created allocation is optional.

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

WARNING

Webhooks notify you of events in business processes, not the success or failure of the initialisation of those processes.

Please be sure to check the HTTP status of the response to your requests and handle failure cases appropriately.