# Investments

## API endpoints <a href="#list-investments" id="list-investments"></a>

{% hint style="success" %}
Authentication: endpoints listed in this page *require* [header authentication](https://docs.powens.com/api-reference/overview/authentication) with a *user token*.
{% endhint %}

## List investments

<mark style="color:blue;">`GET`</mark> `https://{domain}.biapi.pro/2.0/users/{userId}/investments`

List investments related to a user.

#### Path Parameters

| Name                                     | Type            | Description             |
| ---------------------------------------- | --------------- | ----------------------- |
| userId<mark style="color:red;">\*</mark> | Integer or "me" | ID of the related user. |

#### Query Parameters

| Name  | Type   | Description                                  |
| ----- | ------ | -------------------------------------------- |
| label | String | Filter investments using keywords in labels. |
| code  | String | Filter investments by ISIN code.             |

{% tabs %}
{% tab title="200: OK List of investments" %}
Response body: [#investmentslist-object](#investmentslist-object "mention")
{% endtab %}
{% endtabs %}

{% code title="Filtering route aliases:" %}

```
/users/{userId}/accounts/{accountId}/investments
/users/{userId}/connections/{connectionId}/investments
```

{% endcode %}

## Get an investment

<mark style="color:blue;">`GET`</mark> `https://{domain}.biapi.pro/2.0/investments/{investmentId}`

Get a single investment by ID.

#### Path Parameters

| Name                                           | Type    | Description           |
| ---------------------------------------------- | ------- | --------------------- |
| investmentId<mark style="color:red;">\*</mark> | Integer | ID of the investment. |

{% tabs %}
{% tab title="200: OK Investment details" %}
Response body: [#investment-object](#investment-object "mention")
{% endtab %}
{% endtabs %}

## Get history of an investment

<mark style="color:blue;">`GET`</mark> `https://{domain}.biapi.pro/2.0/investments/{investmentId}/history`

Get history of a single investment by ID.

#### Path Parameters

| Name                                           | Type    | Description           |
| ---------------------------------------------- | ------- | --------------------- |
| investmentId<mark style="color:red;">\*</mark> | Integer | ID of the investment. |

{% tabs %}
{% tab title="200: OK Investment history values" %}
Response body: [#investmenthistoryvalueslist-object](#investmenthistoryvalueslist-object "mention")
{% endtab %}
{% endtabs %}

## Data model

### *InvestmentsList* object

<table><thead><tr><th width="221">Property</th><th width="185.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>valuation</code></td><td>Decimal</td><td>Total valuation of all investments.</td></tr><tr><td><code>diff</code></td><td>Decimal</td><td>Total absolute capital gain or loss.</td></tr><tr><td><code>diff_percent</code></td><td>Decimal</td><td>Total relative capital gain or loss.</td></tr><tr><td><code>prev_diff</code></td><td>Decimal</td><td>Total absolute capital gain or loss since the previous value.</td></tr><tr><td><code>prev_diff_percent</code></td><td>Decimal</td><td>Total relative capital gain or loss since the previous value (in ratio, 1 meaning 100%).</td></tr><tr><td><code>calculated</code></td><td>Array of strings</td><td>List of properties of this response that has been calculated rather than directly obtained from the source.</td></tr><tr><td><code>investments</code></td><td>Array of <a href="#investment-object"><em>Investment</em></a> objects</td><td>List of investments.</td></tr></tbody></table>

### *Investment* object

<table><thead><tr><th width="230.33333333333331">Property</th><th width="192">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>Integer</td><td>ID of the investment.</td></tr><tr><td><code>id_account</code></td><td>Integer</td><td>ID of the related account.</td></tr><tr><td><code>label</code></td><td>String</td><td>Display name of the investment.</td></tr><tr><td><code>code</code></td><td>String or null</td><td>Technical code of the investment.</td></tr><tr><td><code>code_type</code></td><td>String</td><td>Code type: <code>ISIN</code> or <code>AMF</code>.</td></tr><tr><td><code>stock_symbol</code></td><td>String or null</td><td>Stock ticker symbol of the investment in the associated stock market.</td></tr><tr><td><code>source</code></td><td>String</td><td>Source of the ISIN code: <code>website</code> or <code>notFound</code>.</td></tr><tr><td><code>description</code></td><td>String or null</td><td>Description of the investment.</td></tr><tr><td><code>quantity</code></td><td>Decimal</td><td>Quantity of stocks of this investment.</td></tr><tr><td><code>unitprice</code></td><td>Decimal</td><td>Buy price of one stock.</td></tr><tr><td><code>unitvalue</code></td><td>Decimal</td><td>Current value of one stock.</td></tr><tr><td><code>valuation</code></td><td>Decimal</td><td>Total current value of the investment.</td></tr><tr><td><code>diff</code></td><td>Decimal</td><td>Absolute capital gain or loss.</td></tr><tr><td><code>diff_percent</code></td><td>Decimal</td><td>Relative capital gain or loss (in ratio, 1 meaning 100%).</td></tr><tr><td><code>prev_diff</code></td><td>Decimal or null</td><td>Absolute capital gain or loss since the previous value.</td></tr><tr><td><code>prev_diff_percent</code></td><td>Decimal or null</td><td>Relative capital gain or loss since the previous value (in ratio, 1 meaning 100%).</td></tr><tr><td><code>vdate</code></td><td>Date</td><td>Value date of the investment.</td></tr><tr><td><code>prev_vdate</code></td><td>Date or null</td><td>Value date of the investment when the previous synchronization occurred.</td></tr><tr><td><code>portfolio_share</code></td><td>Decimal</td><td>Allocation ratio of the investment in the portfolio (1 meaning 100%).</td></tr><tr><td><code>calculated</code></td><td>Array of strings</td><td>List of properties of this response that has been calculated rather than directly obtained from the source.</td></tr><tr><td><code>deleted</code></td><td>Date or null</td><td>Deletion date for investments that no longer exist (<code>null</code> if still present).</td></tr><tr><td><code>last_update</code></td><td>DateTime</td><td>Date of the last synchronization of the investment.</td></tr><tr><td><code>original_currency</code></td><td><a href="../../data-aggregation/currencies#currency-object"><em>Currency</em></a> object or null</td><td>For international investments, currency of the investment (if different from the bank account).</td></tr><tr><td><code>original_valuation</code></td><td>Decimal or null</td><td>For international investments, valuation of the inverstment in the original currency.</td></tr><tr><td><code>original_unitvalue</code></td><td>Decimal or null</td><td>For international investments, current value of one stock in the original currency.</td></tr><tr><td><code>original_unitprice</code></td><td>Decimal or null</td><td>For international investments, buy price of the investment in the original currency.</td></tr><tr><td><code>original_diff</code></td><td>Decimal or null</td><td>For international investments, difference between the buy price and the current valuation in the original currency.</td></tr><tr><td><code>details</code></td><td><a href="#investmentdetails-object"><em>InvestmentDetails</em></a> object or null</td><td>Additional information for the investment (if available and activated).</td></tr></tbody></table>

### *InvestmentDetails* object

<table><thead><tr><th width="242.33333333333331">Property</th><th width="159">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>performance_1_year</code></td><td>Decimal or null</td><td>Performance of the stock between one year ago and today (in ratio, 1 meaning 100%).</td></tr><tr><td><code>performance_3_years</code></td><td>Decimal or null</td><td>Performance of the stock between three years ago and today (in ratio, 1 meaning 100%).</td></tr><tr><td><code>performance_5_years</code></td><td>Decimal or null</td><td>Performance of the stock between five years ago and today (in ratio, 1 meaning 100%).</td></tr><tr><td><code>srri</code></td><td>Decimal or null</td><td>Synthetic Risk and Reward Indicator of the stock (from 1 to 7).</td></tr><tr><td><code>asset_category</code></td><td>String or null</td><td>Asset category of the stock (Actions, Obligations…).</td></tr><tr><td><code>recommended_period</code></td><td>String or null</td><td>Minimum recommended period of investment.</td></tr><tr><td><code>last_update</code></td><td>DateTime or null</td><td>Date of the last synchronization of the additional information.</td></tr></tbody></table>

### *InvestmentHistoryValuesList* object

<table><thead><tr><th width="229.33333333333331">Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>investmentvalues</code></td><td>Array of <a href="#investmenthistory-object"><em>InvestmentHistory</em></a> objects</td><td>List of investment history values.</td></tr></tbody></table>

### *InvestmentHistoryValue* object

<table><thead><tr><th width="236.33333333333331">Property</th><th width="155">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>Integer</td><td>ID of the investment history.</td></tr><tr><td><code>id_investment</code></td><td>Integer</td><td>ID of the related investment.</td></tr><tr><td><code>vdate</code></td><td>Date</td><td>Date of the investment history.</td></tr><tr><td><code>unitvalue</code></td><td>Decimal</td><td>Value of one stock at the date indicated in <code>vdate</code>.</td></tr><tr><td><code>original_currency</code></td><td><a href="https://docs.budget-insight.com/reference/bank-accounts#currency-object"><em>Currency</em></a> or null</td><td>Original currency of the investment history (if different from the account currency).</td></tr><tr><td><code>original_unitvalue</code></td><td>Decimal or null</td><td>Value of one stock in the original currency at the date indicated in <code>vdate</code>.</td></tr></tbody></table>