> For the complete documentation index, see [llms.txt](https://docs.powens.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.powens.com/api-reference/products/wealth-aggregation/investments.md).

# Investments

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

{% hint style="success" %}
Authentication: endpoints listed in this page *require* [header authentication](/api-reference/overview/authentication.md) 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="/pages/HmWmHsTZQ5ujENC5Pnie#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>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.powens.com/api-reference/products/wealth-aggregation/investments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.