Investment

The Investment entity is recovered from not only Brokers (XP, Orama, Rico) but also from retail and business Bank institutions.

The list of investments from an institution can be differentiated based on the type of the investment. Each type of investment has a set of fields that relate to the specific investment type.

 

PropertyTypeOptionalDescription
namestringyesName on the provider.
codestringyesInvestment associated code.
In the case of Mutual Funds it's the CNPJ of the Fund.
isinstringyes12-character ISIN, a globally unique identifier.
numberstringyesInvestment number, not always provided.
ownerstringyesOwner/beneficiary associated with the investment.
currencyCodeCurrencyCodeyesCurrency ISO code of the transaction, ie USD.
typeInvestmentTypenoInvestment type.
subtypeInvestmentSubTypeyesInvestment's subtype
lastMonthRatenumberyesThe interest rate for the last month.
lastTwelveMonthsRatenumberyesAnnual interest for the last 12 months.
annualRatenumberyesAnnual interest for the last year.
dateDateyesAsset value's date.
valuenumberyesQuota's current value at date.
quantitynumberyesQuantity of quota at disposal.
amountnumbernoGross amount of the investment (tax included).
taxesnumberyesIncome taxes applied to the investment.
taxes2numberyesFinancial taxes applied to the investment.
balancenumbernoThe current net balance amount of the investment.
After fees & taxes were applied.
dueDateDateyesExpiration Date.
ratenumberyesFixed rate percentage applied to the investment.
rateTypestringyesType of fixed-rate. (one of CDI | SELIC | DOLAR | EURO | IGPM | IPCA | null)
fixedAnnualRatenumberyesFixed income annual rate (Example: 10.50).
issuerstringyesThe entity that issued the investment.
issueDateDateyesThe date that the entity issued the investment.
amountProfitnumberyesProfit to date over the investment.
amountWithdrawalnumberyesThe amount available to withdraw.
amountOriginalnumberyesAmount originally invested.
statusInvestmentStatusyesCurrent status of the investment.
ACTIVE, PENDING & TOTAL_WITHDRAWAL
institutionInvestmentInstitutionyesBroker or Financial Institution holder of the investment.
This is only returned in CEI B3 Connector.
transactionsInvestmentsTransactionyesList of Investments Transactions associated with Applications or Withdrawals, that affect the amount invested
metadataInvestmentMetadatayesThe metadata object contains "Securities's Data" for portability of Private Pensions.
providerIdstringyesProvider institution internal identifier for the investment

 

Investment's Status

ValueDescription
ACTIVEPurchased and verified
PENDINGValidating purchase
TOTAL_WITHDRAWALSold or transferred

 

Investment's Institution

PropertyTypeOptionalDescription
namestringyesFull name of the institution.
numberstringyesNumber identifier for the institution CNPJ / Other.

 

Investment's Types & Subtypes

To understand the nature of an investment you can rely on the investment type & subtype fields that have accurate relation with the types of investments available in Pluggy.

TypeSubtypeDescription
FIXED_INCOMECRI
CRA
LCI
LCA
LC
TREASURY
DEBENTURES
CDB
Real Estate Receivables Certificate
Agricultural Receivables Certificate
Real State Credit Bill
Agricultural Credit Bill
Bill of Exchange
National Treasury
Corporate Debt
Certificate of Deposit
SECURITYRETIREMENTPrevidencia Privada
MUTUAL_FUNDINVESTMENT_FUND
STOCK_FUND
MULTIMARKET_FUND
EXCHANGE_FUND
FIXED_INCOME_FUND
FIP_FUND
OFFSHORE_FUND
ETF_FUND
Investment Fund
Stock Fund
Multimarket Fund
Exchange Fund (Cambial)
Fixed Income Fund
FIP Fund
Offshore Fund
ETF Fund
EQUITYSTOCK
BDR
REAL_ESTATE_FUND
DERIVATIVES
OPTION
Shares, Stocks
Brazilian Depositary Receipt
Real State Funds
Derivatives
Option
ETFETFExchange-Traded Funds
COESTRUCTURED_NOTE

 

Investment's Metadata

The metadata object holds the Investment Portability information related to Security assets like Private Pension. These fields are used to provide for example "Previdencia Portability".

PropertyTypeOptionalDescription
taxRegimestringyesRegime of the tax used for the asset
proposalNumberstringyesAsset proposal number identification
processNumberstringyesProcess identification number from the institution (susep)

 

Rate Types for Fixed Income Assets

When the assets type is FIXED_INCOME we recover 3 fields associated with the expected investment return. This are rate, rateType & fixedAnnualRate. Below there are some examples of how the rate types are parsed.

ExampleRateRateTypeFixedAnnualRate
100% CDI + 5%100CDI5
IPC-A + 10%100IPCA10
Pré-Fixado 16,76%16.76
12% A.A12

 

Example responses

{
    "id": "ded7d2f1-6b90-44a8-9ace-de747b9f5bfe",
    "number": "123456-2",
    "name": "Pluggy PREVIDENCIA",
    "balance": 1359.39,
    "currencyCode": "BRL",
    "type": "SECURITY",
    "subtype": "RETIREMENT",
    "annualRate": 3.24,
    "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
    "code": null,
    "value": 500,
    "quantity": 3,
    "amount": 1500,
    "taxes": 0,
    "taxes2": 0,
    "date": "2020-07-19T18:27:41.802Z",
    "owner": "John Doe",
    "amountProfit": 359.39,
    "amountWithdrawal": 1310.5,
    "status": "ACTIVE",
    "metadata": {
      "taxRegime": "Progressivo",
      "proposalNumber": "000091322061",
      "processNumber": "15414900845201686"
    },
    "institution": {
      "name": "BANCO BTG PACTUAL S/A",
      "number": "30306294000145"
    }
  }
{
    "id": "f77eccf4-7714-498e-92a9-1bebe70335d9",
    "number": null,
    "name": "Bahia AM Advisory FIC de FIM",
    "balance": 1359.39,
    "currencyCode": "BRL",
    "type": "MUTUAL_FUND",
    "subtype": "INVESTMENT_FUND",
    "lastMonthRate": 0.24,
    "annualRate": 3.24,
    "lastTwelveMonthsRate": 3,
    "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
    "code": "12.345.678/0001-00",
    "value": 500,
    "quantity": 3,
    "amount": 1500,
    "taxes": 40.61,
    "taxes2": 100,
    "date": "2020-07-19T18:27:41.802Z",
    "owner": "John Doe",
    "amountProfit": null,
    "amountWithdrawal": 1310.5,
    "amountOriginal": 1000,
    "status": "ACTIVE",
    "transactions": [
      {
        "tradeDate": "2020-10-01T00:00:00.000Z",
        "date": "2020-10-01T00:00:00.000Z",
        "description": "Aplicação Fundo de Investimento Premium",
        "quantity": 1.25,
        "value": 2,
        "amount": 5,
        "type": "BUY"
      }
    ]
  }
{
    "id": "2a96b873-53bb-4d16-a3d8-385a57e78d7e",
    "number": null,
    "name": "CDB1194KL0Z - BANCO MAXIMA S/A",
    "balance": 2000,
    "currencyCode": "BRL",
    "type": "FIXED_INCOME",
    "subtype": "CDB",
    "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
    "code": "0001-02",
    "amount": 2500,
    "taxes": null,
    "taxes2": null,
    "date": "2020-07-19T18:27:41.802Z",
    "owner": "John Doe",
    "rate": 30,
    "rateType": "CDI",
    "fixedAnnualRate": 10.5,
    "amountProfit": null,
    "amountWithdrawal": 2000,
    "amountOriginal": 1000,
    "dueDate":"2030-07-19T18:27:41.802Z",
    "issuer": "Pluggy",
    "issueDate":"2020-07-19T18:27:41.802Z",
    "status": "ACTIVE"
  }
{
            "id": "5d80be62-d3a3-44e5-aaf7-85d33c7e9a7a",
            "number": null,
            "name": "GGRC11",
            "balance": 118.4,
            "currencyCode": "BRL",
            "type": "EQUITY",
            "subtype": "REAL_ESTATE_FUND",
            "lastMonthRate": null,
            "lastTwelveMonthsRate": null,
            "annualRate": null,
            "itemId": "80c05d1e-0ef7-4939-976d-f1509efd663a",
            "code": "GGRC11",
            "isin": "BRGGRCCTF002",
            "metadata": null,
            "value": 118.4,
            "quantity": 1,
            "amount": 118.4,
            "taxes": null,
            "taxes2": null,
            "date": "2022-06-20T14:43:58.799Z",
            "owner": null,
            "amountProfit": null,
            "amountWithdrawal": 118.4,
            "amountOriginal": 119,
            "transactions":
            [
                {
                    "id": "76689151-2aff-4f32-8308-d9ecffb42254",
                    "amount": 134.99,
                    "description": null,
                    "value": 134.99,
                    "quantity": 1,
                    "tradeDate": "2021-08-15T00:00:00.000Z",
                    "date": "2021-08-15T00:00:00.000Z",
                    "type": "BUY",
                    "netAmount": null,
                    "brokerageNumber": "123456-1",
                    "expenses":
                    {
                        "serviceTax": 0.1,
                        "brokerageFee": 0.04,
                        "incomeTax": 0.08,
                        "other": 0.04,
                        "tradingAssetsNoticeFee": 0.11,
                        "maintenanceFee": 0.12,
                        "settlementFee": 0.02,
                        "clearingFee": 0.1,
                        "stockExchangeFee": 0.1,
                        "custodyFee": 0.05,
                        "operatingFee": 0.03
                    }
                }
            ],
            "dueDate": null,
            "issuer": "GGR COVEPI RENDA FDO INV IMOB",
            "issueDate": null,
            "rate": null,
            "rateType": null,
            "fixedAnnualRate": null,
            "status": "ACTIVE",
            "institution": null,
            "providerId": null
        }
{
            "id": "5af0bd99-b74f-440a-bab3-6ed9155283ee",
            "number": null,
            "name": "ISUS11 STOCK",
            "balance": 2000,
            "currencyCode": "BRL",
            "type": "ETF",
            "subtype": "ETF",
            "lastMonthRate": 0.2,
            "lastTwelveMonthsRate": null,
            "annualRate": null,
            "itemId": "80c05d1e-0ef7-4939-976d-f1509efd663b",
            "code": "ISUS11",
            "isin": "BRISUSCTF003",
            "metadata": null,
            "value": null,
            "quantity": 1,
            "amount": 2000,
            "taxes": null,
            "taxes2": null,
            "date": "2022-06-20T14:43:58.799Z",
            "owner": "John Doe",
            "amountProfit": 0,
            "amountWithdrawal": 2000,
            "amountOriginal": 2000,
            "transactions":
            [
                {
                    "id": "7a102141-b04a-490e-83db-42f09d39c421",
                    "amount": 1499.99,
                    "description": null,
                    "value": 1499.99,
                    "quantity": 1,
                    "tradeDate": "2021-08-15T00:00:00.000Z",
                    "date": "2021-08-15T00:00:00.000Z",
                    "type": "BUY",
                    "netAmount": null,
                    "brokerageNumber": null,
                    "expenses":{}
                }
            ],
            "dueDate": null,
            "issuer": "IT NOW ISE FUNDO DE ÍNDICE",
            "issueDate": null,
            "rate": null,
            "rateType": null,
            "fixedAnnualRate": null,
            "status": "ACTIVE",
            "institution": null,
            "providerId": null
        }
{
            "id": "be7d7a0d-b411-4b88-b0a8-ede1a05aedbb",
            "number": null,
            "name": "SP 500 Ganho Garanti",
            "balance": 5021.2,
            "currencyCode": "BRL",
            "type": "COE",
            "subtype": "STRUCTURED_NOTE",
            "lastMonthRate": null,
            "lastTwelveMonthsRate": null,
            "annualRate": null,
            "itemId": "ed10736c-5330-4242-8a85-204397edb0cc",
            "code": null,
            "isin": null,
            "metadata": null,
            "value": 5027.35,
            "quantity": 1,
            "amount": 5027.35,
            "taxes": null,
            "taxes2": null,
            "date": null,
            "owner": "John Doe",
            "amountProfit": null,
            "amountWithdrawal": null,
            "amountOriginal": 5000,
            "transactions":
            [
                {
                    "id": "b266fcda-b5ee-4181-80b5-273ecb4ff721",
                    "amount": 5000,
                    "description": null,
                    "value": 5000,
                    "quantity": 1,
                    "tradeDate": "2022-01-21T00:00:00.000Z",
                    "date": "2022-01-21T00:00:00.000Z",
                    "type": "BUY",
                    "netAmount": null,
                    "brokerageNumber": null,
                    "expenses":{}
                }
            ],
            "dueDate": "2027-01-27T00:00:00.000Z",
            "issuer": null,
            "issueDate": "2022-01-21T00:00:00.000Z",
            "rate": null,
            "rateType": null,
            "fixedAnnualRate": null,
            "status": "ACTIVE",
            "institution": null,
            "providerId": null
        }

 

📘

See the Investment product, in our API reference for more information.