Skip to main content

Custom Security

Custom securities (GENERIC type) are securities created and managed by the organization itself. They allow you to represent, in a portfolio, investments that are not available in Gorila's database, such as real estate, stakes in private companies or offshore private equity funds. Since these securities have no market source, the organization is responsible for providing their prices and events.

As with any other security created by the organization, custom securities are only available to your organization's API keys.

Creation​

To create a custom security, use the Create Security endpoint with the CUSTOM type. The main fields are:

  • name and description (required): identify the security.
  • assetClass (required): highest-level asset class (CASH, CURRENCY, FIXED_INCOME, MULTIMARKET, OFFSHORE, STOCKS or TANGIBLE).
  • initialDate (required): the security's initial date.
  • maturityDate: the maturity date, when there is one.
  • classificationId: the security's place in the security classification tree.
  • daysToSettlement: number of days for the proceeds of a sale to become available. It is used in the liquidity calculation.
  • taxIncentivized: whether the security has tax incentives.
//REQUEST
//POST https://core.gorila.com.br/securities

{
  "type": "CUSTOM",
  "name": "Apartment",
  "description": "Apartment located in São Paulo",
  "assetClass": "TANGIBLE",
  "initialDate": "2022-04-04",
  "classificationId": "TANGIBLE_GENERIC"
}

The response will return the newly created security's ID (securityId), which must be used to register prices, events and transactions:

//RESPONSE

{
  "id": 44789072
}

To list the securities created by your organization, use the securityProvider=ORGANIZATION filter in the List Securities endpoint.

Prices​

The organization provides the prices of a custom security through the Upsert Security Prices endpoint, which accepts up to 1,000 prices per request. If there is already a price on the informed date, it is replaced. On days without a price, the last available price is used.

//REQUEST
//PUT https://core.gorila.com.br/securities/{securityId}/prices

{
  "prices": [
    { "referenceDate": "2024-01-31", "price": 1000.00 },
    { "referenceDate": "2024-02-29", "price": 1012.50 }
  ]
}

To read the registered prices, use List Security Prices. To remove the price of a specific date, use Delete Security Prices.

Events​

The events of a custom security are also registered by the organization, through the Create Security Event endpoint. The available types are:

  • Cash events: amortization (CASH_AMORTIZATION), unscheduled amortization (CASH_AMORTIZATION_UNSCHEDULED), dividends (CASH_DIVIDEND), income (CASH_INCOME), interest (CASH_INTEREST), interest on equity (CASH_JSCP), premiums (CASH_PREMIUM) and return of capital (CASH_RETURN_OF_CAPITAL). These events impact the portfolio's cash and require the amount paid per unit of the security (unitValue).
  • Expiration (EXPIRATION): impacts custody. Once registered, it is the equivalent of a full sale, at the settlement price (settlementPrice), for every portfolio holding the security on the event date. Therefore, positions are automatically closed on the expiration date.

Every event has a reference date (referenceDate), the ex-date that defines who is entitled to the event, and a payment date (paymentDate).

//REQUEST
//POST https://core.gorila.com.br/securities/{securityId}/events

{
  "type": "CASH_AMORTIZATION",
  "referenceDate": "2024-01-31",
  "paymentDate": "2024-02-05",
  "unitValue": 2.5
}

When registering cash events, keep in mind their impact on the security's price. Usually, a payment of BRL X per unit of the security reduces its price in the same proportion. Therefore, you also need to register the price drop on the same date, to offset the amount paid in the event. Otherwise, the Profit & Loss (P&L) will have a positive distortion that does not reflect reality.

Registered events can be read with List Security Custom Events, updated with Update Security Event and deleted with Delete Security Event. Once registered, they show up in the Portfolio Security Events like any other event. The full list of Gorila's event types is available at List Security Event Types.

Classification​

Any security can be reclassified, including custom ones. If you want the created security to belong to a given class or subclass, inform the desired classification in the classificationId field, either on creation or when updating the security. More details about classes and reclassification are available in the Security Classification documentation.

Update and deletion​

Through the Update Security by ID endpoint, you can change a custom security's name, description, maturity date, tax incentive, days to settlement and classification. Custom securities can also be deleted through the Delete Security by ID endpoint.