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.
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.\n\nNote: requires feature enabled and Pro subscription. |
providerId | string | yes | Provider institution internal identifier for the investment. |
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 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 |
SECURITY | RETIREMENT PGBL VGBL | Previdencia Privada |
MUTUAL_FUND | INVESTMENT_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 |
EQUITY | STOCK BDR REAL_ESTATE_FUND DERIVATIVES OPTION | Shares, Stocks Brazilian Depositary Receipt Real State Funds Derivatives Option |
ETF | ETF | Exchange-Traded Funds |
COE | STRUCTURED_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".
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 [email protected] 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. This 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
{
"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."
}
}
}
{
"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.
Updated 3 months ago