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

yes

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 interest rate for the last month.

lastTwelveMonthsRate

number

yes

Annual interest for the last 12 months.

annualRate

number

yes

Annual interest for the last year.

date

Date

yes

Asset value's date.

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

Profit to date over the investment.

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

InvestmentsTransaction

yes

List of Investments Transactions associated with Applications or Withdrawals, that affect the amount invested

metadata

InvestmentMetadata

yes

The metadata object contains "Securities's Data" for portability of Private Pensions.

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

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)

 

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