# List investments

## ▶️ Usage

With the List Investments method, you can:

1. [Required] List investments related to a specific link.id (using the link query parameter).
2. Get the details of a specific investment.id (using the id query parameter).

## 📖 Pagination

This method returns a paginated response (default: 100 items per page). You can use the page_size query parameter to increase the number of items returned to a maximum of 1000 items. You can use the page query parameter to navigate through the results. For more details on how to navigate Belvo's paginated responses, see our Pagination Tips article.

## 🔦 Filtering Responses

Please see the query list below for a list of fields that you can filter your responses by. For more information on how to use filters, see our Filtering responses article.

Endpoint: GET /api/br/investments/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `link` (string, required)
    The link.id you want to filter by.
    Example: "8848bd0c-9c7e-4f53-a732-ec896b11d4c4"

  - `page_size` (integer)
    Indicates how many results to return per page. By default we return 100 results per page. 

ℹ️ The minimum number of results returned per page is 1 and the maximum is 1000. If you enter a value greater than 1000, our API will default to the maximum value (1000).
    Example: 100

  - `page` (integer)
    A page number within the paginated result set.
    Example: 1

  - `id` (string)
    Return information only for this resource id.
    Example: "24ccab1d-3a86-4136-a6eb-e04bf52b356f"

  - `id__in` (array)
    Return information for these resource ids.
    Example: ["6b3dea0f-be29-49d1-aabe-1a6d588642e6"]

  - `link__in` (array)
    Return results only for these link.ids.
    Example: ["5722d0ba-69d7-42dc-8ff5-33767b83c5d6"]

  - `omit` (string)
    Omit certain fields from being returned in the response. For more information, see our Filtering responses DevPortal article.

  - `fields` (string)
    Return only the specified fields in the response. For more information, see our Filtering responses DevPortal article.

  - `type` (string)
    Return investments with this type. Can be either BANCARIA, CREDITO, VARIABLE , FUND, or BOND.
    Example: "VARIABLE"

  - `type__in` (array)
    Return investments of this type. Can be either BANCARIA, CREDITO, VARIABLE , FUND, or BOND.
    Example: ["VARIABLE"]

  - `created_at` (string)
    Return items that were last updated in Belvo's database on this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gt` (string)
    Return items that were last updated in Belvo's database after this date (in YYYY-MM-DD format).
    Example: "2022-05-05"

  - `created_at__gte` (string)
    Return items that were last updated in Belvo's database after or on this date (in YYYY-MM-DD format).
    Example: "2022-05-04"

  - `created_at__lt` (string)
    Return items that were last updated in Belvo's database before this date (in YYYY-MM-DD format).
    Example: "2022-04-01"

  - `created_at__lte` (string)
    Return items that were last updated in Belvo's database before or on this date (in YYYY-MM-DD format).
    Example: "2022-03-30"

  - `created_at__range` (array)
    Return accounts that were last updated in Belvo's database between two dates (in YYYY-MM-DD format). The first value indicates the start of the range and the second value indicates the end of the range.
    Example: ["2022-01-01","2022-12-31"]

## Response 200 fields (application/json):

  - `count` (integer)
    The total number of results in your Belvo account.
    Example: 130

  - `next` (string,null)
    The URL to next page of results. Each page consists of up to 100 items. If there are not enough results for an additional page, the value is null.

In our documentation example, we use {endpoint} as a placeholder value. In production, this value will be replaced by the actual endpoint you are currently using (for example, accounts or owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"

  - `previous` (string,null)
    The URL to the previous page of results. If there is no previous page, the
value is null.

  - `results` (array)
    Array of investment objects.

  - `results.id` (string)
    The unique identifier created by Belvo used to reference the current investment.
    Example: "5359ddc5-31fc-4346-934b-cc24630a8d06"

  - `results.type` (string)
    The type of investment: Can be either

  - FIXED_INCOME_BANKING (Renda Fixa Bancária)
  - FIXED_INCOME_CREDIT (Renda Fixa Crédito)
  - VARIABLE_INCOME (Renda Variável)
  - TREASURY_BOND (Tesouro Direto)
  - INVESTMENT_FUND (Fundos de Investimento)
    Example: "FIXED_INCOME_BANKING"

  - `results.issuer_id_number` (string,null)
    The CNPJ number of the issuing institution. For Investment Funds, this is the CNPJ of the fund.

> 🚧 Not applicable for TREASURY_BOND investments.
    Example: "10187609364567"

  - `results.isin_number` (string,null)
    The ISO-6166 International Securities Identification Number (ISIN) for the financial instrument.
    Example: "BRCST4CTF001"

  - `results.currency` (string)
    The three-letter currency code (ISO-4217) of the investment. For example, BRL for Brazilian Real.
    Example: "BRL"

  - `results.product_name` (string)
    The name of the investment product.

- For FIXED_INCOME_BANKING, this can be: CDB, RDB, LCI, or LCA.
- For FIXED_INCOME_CREDIT, this can be: DEBENTURES, CRI, or CRA.
- For INVESTMENT_FUND, this will be the name of the fund. For example: CONSTELLATION MASTER FIA
- For TREASURY_BOND, this will be the name of the bond. For example: Tesouro Selic 2025.
- For VARIABLE_INCOME_INCOME, this will be the name of the stock. For example AAPL.
    Example: "CONSTELLATION MASTER FIA"

  - `results.is_tax_exempt` (boolean)
    Indicates if the investment is exempt from taxes.

> 🚧 Only applicable for FIXED_INCOME_CREDIT investments.

  - `results.clearing_code` (string,null)
    The clearing code of the investment.

> 🚧 Only applicable for FIXED_INCOME_BANKING and FIXED_INCOME_CREDIT.
    Example: "CDB421GPXXX"

  - `results.due_date` (string,null)
    The maturity date of the financial instrument. 

> 🚧 Only applicable for FIXED_INCOME_BANKING, FIXED_INCOME_CREDIT, and TREASURY_BOND investments.
    Example: "2022-01-01"

  - `results.issue_date` (string,null)
    The date the financial instrument was issued.

> 🚧 Only applicable for FIXED_INCOME_BANKING and FIXED_INCOME_CREDIT.
    Example: "2021-01-01"

  - `results.purchase_date` (string,null)
    The date the financial instrument was purchased.

> 🚧 Only applicable for FIXED_INCOME_BANKING, FIXED_INCOME_CREDIT, and TREASURY_BOND investments.
    Example: "2021-01-01"

  - `results.grace_period_date` (string,null)
    The grace period date of the financial instrument.

> 🚧 Only applicable for FIXED_INCOME_BANKING and FIXED_INCOME_CREDIT.
    Example: "2021-01-01"

  - `results.issue_unit_price` (number,null)
    The unit price of the financial instrument at the time of issuance.

> 🚧 Only applicable for FIXED_INCOME_BANKING and FIXED_INCOME_CREDIT.
    Example: 1000

  - `results.balance` (object)
    The balance of the investment instrument, as of the reference_date.

  - `results.balance.reference_date` (string)
    The date and time that the balance was calculated for the investment instrument, in YYYY-MM-DDTHH:MM:SSZ format.
    Example: "2022-07-21T17:32:00Z"

  - `results.balance.gross_value` (number)
    The gross value of the investment instrument.
    Example: 1000

  - `results.balance.blocked_amount` (number)
    The amount of the investment instrument that is blocked or unavailable for transactions.
    Example: 100

  - `results.balance.quantity` (number)
    The number of units, quotas, or assets held on the reference date.
    Example: 100

  - `results.balance.gross_unit_price` (number,null)
    The current gross unit value of the investment on the reference date
    Example: 10

  - `results.balance.net_value` (number,null)
    The net value of the investment after deductions for taxes, fees, and other charges, as of the reference date.
    Example: 900

  - `results.balance.withheld_amount` (number,null)
    The amount of the investment instrument that has been withheld or deducted from the net value.
    Example: 10

  - `results.balance.transaction_fee` (number,null)
    The fees and taxes charged for the transaction.
    Example: 5

  - `results.balance.purchase_unit_price` (number,null)
    The unit price at the time of purchase for the security or asset.
    Example: 10

  - `results.balance.pre_fixed_rate` (number,null)
    The pre-fixed remuneration rate for the income product.
    Example: 0.05

  - `results.balance.post_fixed_rate` (number,null)
    The percentage of the post-fixed indexer for the income product.
    Example: 0.05

  - `results.balance.penalty_fee` (number,null)
    The penalty (fine) for delays in payments, as defined in the contract.
    Example: 10

  - `results.balance.late_payment_fee` (number,null)
    The interest charged for delayed payments.
    Example: 10

  - `results.balance.closing_price` (number,null)
    The closing price of the investment on the reference date.
    Example: 10

  - `results.balance.unit_price_factor` (number,null)
    The factor used to calculate the unit price.
    Example: 1

  - `results.remuneration` (object)
    The remuneration details of the investment instrument.

  - `results.remuneration.pre_fixed_rate` (number,null)
    The fixed interest rate defined at issuance, expressed as a decimal (for example 0.150000 represents 15%).
    Example: 0.05

  - `results.remuneration.post_fixed_rate` (number,null)
    The post-fixed interest rate defined at issuance, expressed as a decimal (for example 0.150000 represents 15%).
    Example: 0.05

  - `results.remuneration.rate_type` (string,null)
    The type of remuneration rate applied to the financial instrument. Can be either:
  - LINEAR
  - EXPONENCIAL
    Example: "LINEAR"

  - `results.remuneration.rate_periodicity` (string,null)
    The frequency that the remuneration rate is applied to the financial instrument. Can be either:
  - DIARIO
  - MENSAL
  - ANUAL
  - SEMESTRAL
    Example: "MENSAL"

  - `results.remuneration.calculation_base` (string,null)
    Indicates whether the remuneration or interest calculation is based on business days (dias úteis) or calendar days (dias corridos).
- DIAS_UTEIS
  - DIAS_CORRIDOS
    Example: "DIAS_CORRIDOS"

  - `results.remuneration.indexer` (string,null)
    The index used as a reference to calculate the profitability or returns of the financial instrument. Can be one either:
  - CDI 
  - DI 
  - TR 
  - IPCA 
  - IGP_M 
  - IGP_DI 
  - INPC 
  - BCP 
  - TLC 
  - SELIC 
  - PRE_FIXADO 
  - OUTROS
    Example: "CDI"

  - `results.remuneration.indexer_additional_info` (string,null)
    Additional information regarding the indexer rate. Required when indexer is set to OUTROS.
    Example: "IPCA + 5%"

  - `results.classification_details` (object,null)
    The classification details of the investment instrument.

> 🚧 Only applicable for INVESTMENT_FUND investments.
>
> This object is only applicable for INVESTMENT_FUND investments. For all other investment types, this object will be null.

  - `results.classification_details.category` (string,null)
    The investment fund's category, as defined by ANBIMA's classification standards. Can be one of:
  - RENDA_FIXA
  - ACOES
  - MULTIMERCADO
  - CAMBIAL
    Example: "ACOES"

  - `results.classification_details.class` (string,null)
    The class within the investment fund's category, as defined by ANBIMA's classification standards.
    Example: "Ações Livre"

  - `results.classification_details.subclass` (string,null)
    The subclass of the investment fund, as defined by ANBIMA's classification standards.
    Example: "Ações Livre"

  - `results.voucher_payment_details` (object)
    The voucher payment (also known as coupon payments) details of the investment instrument.

> 🚧 Only applicable for FIXED_INCOME_CREDIT and TREASURY_BOND investments.
>
> This object is only applicable for FIXED_INCOME_CREDIT and TREASURY_BOND investments. For all other investment types, this object will be null.

  - `results.voucher_payment_details.is_voucher_payment` (boolean)
    Indicates whether the financial instrument pays periodic interest (voucher payments).
    Example: true

  - `results.voucher_payment_details.periodicity` (string,null)
    The frequency that the voucher payments are made. Required when is_voucher_payment is set to true. Can be one of:
  - MENSAL 
  - TRIMESTRAL 
  - SEMESTRAL 
  - ANUAL 
  - IRREGULAR 
  - OUTROS
    Example: "MENSAL"

  - `results.voucher_payment_details.periodicity_additional_info` (string,null)
    Additional information about the voucher payment periodicity. Required when periodicity is set to OUTROS.
    Example: "30/360"

  - `results.debtor_details` (object,null)
    The debtor details of the investment instrument.

> 🚧 Only applicable for FIXED_INCOME_CREDIT investments.
>
> This object is only applicable for FIXED_INCOME_CREDIT investments. For all other investment types, this object will be null.

  - `results.debtor_details.name` (string)
    The name of the debtor.
    Example: "Roberto Marino"

  - `results.debtor_details.id_document_number` (string)
    The debtor's identification document number (CNPJ).
    Example: 12345678901

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (access_to_resource_denied) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    A short description of the error. 


For access_to_resource_denied errors, the description is:
  
  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    A unique error code (not_found) that allows you to classify and handle the error programmatically.
    Example: "not_found"

  - `message` (string)
    A short description of the error.


For not_found errors, the description is:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (unexpected_error) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 500 unexpected_error errors.
    Example: "unexpected_error"

  - `message` (string)
    A short description of the error. 


For unexpected_error errors, the description is:
  
  - Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"