Portfolios

Endpoints

The portfolios endpoint allows you to list all portfolios you've created in BETTER, as well as retrieve details about a particular portfolio.

In both the portfolio list and portfolio detail view, you will see a list of buildings that belong to a portfolio. However, in the portfolio list those buildings will just be a list of building IDs, while in the detail view you will see top-level information for each building in the portfolio.

Creating a Portfolio

You can create a portfolio by sending a POST request to the portfolios endpoint. You must send in at least one of information: the name for the portfolio.

That information -- in JSON form in the body of the POST request -- should look like this:

{
    "name": "Some portfolio name",
}

You can optionally provide a three character value for the portfolio's default currency. (Please see the OpenAPI documentation for allowed values.)

For example:

{
    "name": "Some portfolio name",
    "currency": "EUR"
}

Note that if you do not provide a currency, BETTER will use the default currency defined in your user settings. If you haven't modified this value, it will be set to USD by default.

Listing Portfolios

You can get a complete list of portfolios by sending a GET request to the /api/v1/portfolios/ endpoint. The returned information will include various properties for each portfolio, including:

• a list of IDs for buildings in that portfolio.
• a list IDs for portfolio analytics that have been generated for that portfolio.
• the default currency for that portfolio.

...and a few other properties like the date the portfolio was created, last updated, etc.

Note that the benchmark statistics for a portfolio is only available in the detail view.

To view more detail about the buildings and portfolio-level analytics for an individual portfolio, you can use the "Retrieve" operation described below.

Retrieve a Portfolio

You can retrieve a complete description of a portfolio by sending a GET request to the endpoint for that portfolio, using the portfolio's ID.

For example, to retrieve the details of a portfolio with ID of 9 would require sending a GET request to /api/v1/portfolios/9/

The response will include:

• a list of the portfolio's buildings as Building objects in the buildings list.
• a list of any generated analytics as Portfolio Analytics objects in the analytics list.
• details on any benchmark statistics in the benchmark_stastics object

An empty Portfolio will look like this:

 {
    "id": 9,
    "name": "My Portfolio",
    "portfolio_currency": "USD",
    "benchmark_statistics": null,
    "total_area": 0.0,
    "date_created": "2021-03-16T20:58:55.132496Z",
    "date_updated": "2021-03-16T20:58:55.132536Z",
    "buildings": [],
    "analytics": []
}

Editing a Portfolio

You can edit a portfolio by sending a PATCH request to the portfolio endpoint, including the portfolio ID, in the same manner as the 'retrieve' process described above (.e.g /api/v1/portfolios/9/).

You could update the portfolio's name with a PATCH request like:

{
    "name": "My updated portfolio name"
}

If you want to add, update or remove buildings in a portfolio please see the Buildings API docs.

If you want to add, update or remove portfolio analytics for a portfolio, please see the Portfolio Analytics API docs.

Deleting a Portfolio

You can delete a portfolio by sending a DELETE request to that particular portfolio's endpoint, using the portfolio ID (in the same way as retrieve or update, e.g. /api/v1/portfolios/9/ ).

When you delete a portfolio, all buildings and building analytics in that portfolio are also deleted. Furthermore, any generated portfolio analytics will also be deleted. In essence, that portfolio is no more.

You cannot delete your user's DEFAULT portfolio. If you want to remove buildings and/or analytics from your DEFAULT portfolio,please see the Buildings and Portfolio Analytics API docs.