Investment

The Investment entity is recovered from not only Brokers (XP, Clear) 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.

Property	Type	Optional	Description
name	string	No	Name on the provider.
code	string	Yes	Investment associated code. In the case of Mutual Funds it's the CNPJ of the Fund.
isin	string	Yes	12-character ISIN, a globally unique identifier.
number	string	Yes	Investment number, not always provided.
owner	string	Yes	Owner/beneficiary associated with the investment.
currencyCode	CurrencyCode	Yes	Currency ISO code of the transaction, ie USD.
type	InvestmentType	No	Investment type.
subtype	InvestmentSubType	Yes	Investment's subtype.
lastMonthRate	number	Yes	The performance rate for the last month. This value is returned for funds.
lastTwelveMonthsRate	number	Yes	The performance rate last 12 months. This value is returned for funds.
annualRate	number	Yes	Performance rate for the last year. This value is returned for funds.
date	Date	Yes	Asset value's reference date. ie. When recovering assets over the weekend, the date will probably be the last business day.
value	number	Yes	Quota's current value at `date`.
quantity	number	Yes	Quantity of quota at disposal.
amount	number	No	Gross amount of the investment (tax included).
taxes	number	Yes	Income taxes applied to the investment.
taxes2	number	Yes	Financial taxes applied to the investment.
balance	number	No	The current net balance amount of the investment. After fees & taxes were applied.
dueDate	Date	Yes	Expiration Date.
rate	number	Yes	Fixed rate percentage applied to the investment.
rateType	string	Yes	Type of fixed-rate. (one of `CDI` \| `SELIC` \| `DOLAR` \| `EURO` \| `IGPM` \| `IPCA` \| null)
fixedAnnualRate	number	Yes	Fixed income annual rate (Example: 10.50).
issuer	string	Yes	The entity that issued the investment.
issueDate	Date	Yes	The date that the entity issued the investment.
amountProfit	number	Yes	Net profit to date over the investment. If negative, is loss.
amountWithdrawal	number	Yes	The amount available to withdraw.
amountOriginal	number	Yes	Amount originally invested.
status	InvestmentStatus	Yes	Current status of the investment. ACTIVE, PENDING & TOTAL_WITHDRAWAL
institution	InvestmentInstitution	Yes	Broker or Financial Institution holder of the investment. This is only returned in CEI B3 Connector.
transactions (deprecated)	InvestmentsTransaction	Yes	List of Investments Transactions associated with Applications or Withdrawals, that affect the amount invested. This field will not be present on Applications created after March 21st, 2023. Use the paginated Investment Transactions endpoint instead.
metadata	InvestmentMetadata \| null	Yes	The metadata object contains "Securities's Data" for portability of Private Pensions. Note: requires feature enabled and Pro subscription.
providerId	string	Yes	Provider institution internal identifier for the investment.
gracePeriodDate	Date	Yes	Date when the grace period ends. Populated for fixed-income investments (CDB, LCI, LCA, CRI, CRA, Debenture). null for all other investment types.

Investment's Status #

Value	Description
ACTIVE	Purchased and verified
PENDING	Validating purchase
TOTAL_WITHDRAWAL	Sold or transferred

Investment's Institution #

Property	Type	Optional	Description
name	string	Yes	Full name of the institution.
number	string	Yes	Number 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.

Type	Subtype	Description
FIXED_INCOME	CRI	Real Estate Receivables Certificate
FIXED_INCOME	CRA	Agricultural Receivables Certificate
FIXED_INCOME	LCI	Real State Credit Bill
FIXED_INCOME	LCA	Agricultural Credit Bill
FIXED_INCOME	LC	Bill of Exchange
FIXED_INCOME	TREASURY	National Treasury
FIXED_INCOME	DEBENTURES	Corporate Debt
FIXED_INCOME	CDB	Certificate of Deposit
FIXED_INCOME	LIG	Guaranteed Real Estate Letter
FIXED_INCOME	LF	Financial Bill
SECURITY	RETIREMENT	Previdencia Privada
SECURITY	PGBL	Previdencia Privada
SECURITY	VGBL	Previdencia Privada
MUTUAL_FUND	INVESTMENT_FUND	Investment Fund
MUTUAL_FUND	STOCK_FUND	Stock Fund
MUTUAL_FUND	MULTIMARKET_FUND	Multimarket Fund
MUTUAL_FUND	EXCHANGE_FUND	Exchange Fund (Cambial)
MUTUAL_FUND	FIXED_INCOME_FUND	Fixed Income Fund
MUTUAL_FUND	FIP_FUND	FIP Fund
MUTUAL_FUND	OFFSHORE_FUND	Offshore Fund
MUTUAL_FUND	ETF_FUND	ETF Fund
EQUITY	STOCK	Shares, Stocks
EQUITY	BDR	Brazilian Depositary Receipt
EQUITY	REAL_ESTATE_FUND	Real State Funds
EQUITY	DERIVATIVES	Derivatives
EQUITY	OPTION	Option
ETF	ETF	Exchange-Traded Funds
COE	STRUCTURED_NOTE	Structured Note

Have in mind Some banks such as NuBank and PicPay have investment options called "Cofrinhos" and "Caixinhas", which configure as CDBs. Thus, they are covered by the connection and should show on the investments section as well.

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".

Property	Type	Optional	Description
taxRegime	string	Yes	Regime of the tax used for the asset.
proposalNumber	string	Yes	Asset proposal number identification.
processNumber	string	Yes	Process identification number from the institution (`susep`).
fundName	string	Yes	Name of the fund associated to the Security investment (can be different to the investment `name` property).
insurer	Company	Yes	The insurer company of the Security Fund, when the process number is identified, the insurer will always be returned.

Retirement Portability Product This dataset is part of the Retirement Portability service, and won't be returned on the response of the investment until enabled. Please contact support@pluggy.ai or chat with us to test this feature.

Rate Types for Fixed Income Assets #

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

Example	Rate	RateType	FixedAnnualRate
100% CDI + 5%	100	CDI	5
IPC-A + 10%	100	IPCA	10
Pré-Fixado 16,76%			16.76
12% A.A			12

Example responses #

Previdencia

{
  "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",
    "insurer": {
      "cnpj": "51.990.695/0001-37",
      "name": "BRADESCO VIDA E PREVIDÊNCIA S.A."
    }
  }
}

Mutual Fund

{
  "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"
    }
  ]
}

CDB

{
  "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"
}

Real Estate Fund

{
  "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
}

ETF

{
  "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
}

COE

{
  "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 Investment in our API reference for more information.

Investment's Status#

Investment's Institution#

Investment's Types & Subtypes#

Investment's Metadata#