Holdings Import v2 📃
Try Demo

Holdings Import v2 📃

With Holdings Import, you can easily import the latest snapshot of a user’s security (stock and ETF) and smallcase holdings on your platform.

What's new? ✨

smallcase Gateway now provides a new format for the holdings import flow:

  1. Positions are shown separately at an NSE and BSE level since cross-exchange trading is not allowed by most brokers on the same day.
  2. BSE-only listed holdings are being shown in v2 along with an average price that is being picked up from the broker itself.
  3. The transactable quantity is NSE holdings + the NSE positions. This is being shared because users might have BSE positions that are not tradable via smallcase Gateway. Moreover, the user can hold a quantity in smallcases that the user might / might not want to sell.
  4. Names of stocks are shared along with the NSE and BSE tickers.
  5. The quantity of stocks invested via smallcases is available as a new field since the user might/might not want to sell.
v1 holdings data had the following limitations which are resolved with the new v2:
  1. positions vs holdings: partners could not differentiate between holdings and positions quantity.
    2. BSE-only listed: such stock details were not available in holdings data
    3. tradeable quantity: partners were not able to determine how much of the total quantity is actually tradeable by the user. This was because users might have BSE positions that are not sellable via smallcase Gateway. Moreover, the user can hold a quantity in smallcase that the user might / might not want to sell.
    4. smallcase qty excluded from stock quantity: stock holdings that were part of any smallcase were not shared in stock details. Example: quantity of stock A will not include a quantity that is part of the user's smallcase holdings. With v2, the total quantity will be shared along with smallcase quantity to offer granular data to you.

Implementation details 🚀

The user flow for holdings import remains the same. The implementation change is in the request parameters of the following APIs:

  1. Create transaction: holdings import

    To create a transactionId for triggering the holdings import in the v2 format, pass the body params as mentioned below:

    {
   "intent": "HOLDINGS_IMPORT",
   "version": "v2"
}

  2. Fetch holdings API

    To fetch the holdings response in the v2 format, pass the query param ?version=v2 in the request URL.

Response Structure 💁

With the new v2 format, the structure of securities and smallcases array have been revamped:

  • securities[]: array of objects with each element representing a stock/ETF holding of the user

    • holdings: represents the stock information for the demat holding

      • quantity: holdings quantity
      • averagePrice: average buy price of the stock holdings

    • positions: represents the information about the positions of the stock

      • nse: positions under the exchange NSE
        • quantity: net quantity under the NSE positions (net quantity here represents buyPositions - sellPositions)
        • averagePrice: net average price for the NSE positions
      • bse: positions under the exchange BSE
        • quantity: net quantity under the BSE positions (net quantity here represents buyPositions - sellPositions)
        • averagePrice: net average price for the BSE positions

    • smallcaseQuantity: represents the quantity of the stock, which belongs to any invested smallcase

    • transactableQuantity: represents the quantity of the stock, which is transactable via smallcase (Note: transactableQuantity also includes the stock quantity that is part of the user's smallcase investment)

    • collateralQuantity: represents the quantity of the stock, held in the user's Demat account for which the user has a loan offered by a stockbroker against the shares

    • nseTicker: ticker symbol for the stock on the NSE

    • bseTicker: ticker symbol for the stock on the BSE

    • isin: ISIN of the stock

    • name: stock name

  • smallcases: object containing details about the user's smallcase investments

    • public[]: array of public smallcases that the user has invested in

      • scid: the unique identifier of the smallcase
      • name: smallcase name
      • investmentDetailsURL: smallcase platform URL of user's investment details page
      • shortDescription: description of the smallcase
      • imageUrl: smallcase logo URL
      • stats: investment stats
        • currentValue: current market value of the smallcase
        • totalReturns: total returns of the smallcase
      • constituents[]: array of constituents that are part of the user's investment
        • ticker: NSE ticker of the constituent
        • shares: quantity of tickers that are part of this smallcase

    • private: object containing details about the user's investment in private (fee-based) smallcases

      • stats: an object containing overall stat's about user combined private smallcase investment
        • currentValue: aggregated current market value of investments in all fee-based smallcases combined
        • totalReturns: aggregated total returns of investments in all fee-based smallcases combined

Sample response 📃

{
  "success": true,
  "errors": null,
  "data": {
    "smallcases": {
      "public": [
        {
          "scid": "SCAW_0001",
          "name": "All Weather Investing",
          "investmentDetailsURL": "https://smallcase.zerodha.com/details/5f2d22636678954954f29a2d?",
          "shortDescription": "Diversify with equity, gold & fixed income ETFs for recession-proof investing",
          "imageUrl": "https://assets.smallcase.com/images/smallcases/200/SCAW_0001.png",
          "stats": {
            "currentValue": 4921.89,
            "totalReturns": -36.65253999999927
          },
          "constituents": [
            {
              "ticker": "NIFTYBEES",
              "shares": 10
            },
            {
              "ticker": "JUNIORBEES",
              "shares": 3
            },
            {
              "ticker": "LIQUIDBEES",
              "shares": 1
            },
            {
              "ticker": "GOLDBEES",
              "shares": 39
            }
          ]
        }
      ],
      "private": {
        "stats": {
          "currentValue": 57.31,
          "totalReturns": 1.3100000000000023
        }
      }
    },
    "securities": [
      {
        "holdings": {
          "quantity": 4,
          "averagePrice": 36.68
        },
        "positions": {
          "nse": {
            "quantity": 1,
            "averagePrice": 34.1
          },
          "bse": {
            "quantity": 1,
            "averagePrice": 34.1
          }
        },
        "transactableQuantity": 5,
        "smallcaseQuantity": 2,
        "nseTicker": "J&KBANK",
        "bseTicker": "J&KBANK",
        "isin": "INE168A01041",
        "name": "Jammu and Kashmir Bank Ltd"
      },
      {
        "holdings": {
          "quantity": 1,
          "averagePrice": 28.4
        },
        "positions": {
          "nse": {
            "quantity": 0,
            "averagePrice": 0
          },
          "bse": {
            "quantity": 0,
            "averagePrice": 0
          }
        },
        "transactableQuantity": 1,
        "smallcaseQuantity": 0,
        "nseTicker": "MASPTOP50",
        "bseTicker": "MASPTOP50",
        "isin": "INF769K01HP3",
        "name": "Mirae Asset S&P 500 Top 50 ETF"
      },
      {
        "holdings": {
          "quantity": 1,
          "averagePrice": 10.53
        },
        "positions": {
          "nse": {
            "quantity": 0,
            "averagePrice": 0
          },
          "bse": {
            "quantity": 0,
            "averagePrice": 0
          }
        },
        "transactableQuantity": 1,
        "smallcaseQuantity": 0,
        "nseTicker": "AXISBPSETF",
        "bseTicker": null,
        "isin": "INF846K01Z04",
        "name": "Axis AAA Bond Plus SDL ETF-2026 Matur. Reg. Growth"
      },
      {
        "holdings": {
          "quantity": 1,
          "averagePrice": 9.8
        },
        "positions": {
          "nse": {
            "quantity": 0,
            "averagePrice": 0
          },
          "bse": {
            "quantity": 0,
            "averagePrice": 0
          }
        },
        "transactableQuantity": 1,
        "smallcaseQuantity": 0,
        "nseTicker": "SUZLON",
        "bseTicker": "SUZLON",
        "isin": "INE040H01021",
        "name": "Suzlon Energy Ltd"
      },
      {
        "holdings": {
          "quantity": 1,
          "averagePrice": 48.5
        },
        "positions": {
          "nse": {
            "quantity": 0,
            "averagePrice": 0
          },
          "bse": {
            "quantity": 0,
            "averagePrice": 0
          }
        },
        "transactableQuantity": 1,
        "smallcaseQuantity": 0,
        "nseTicker": "ICICIB22",
        "bseTicker": "ICICIB22",
        "isin": "INF109KB15Y7",
        "name": "Bharat 22 ETF"
      },
      {
        "holdings": {
          "quantity": 1,
          "averagePrice": 36.05
        },
        "positions": {
          "nse": {
            "quantity": 0,
            "averagePrice": 0
          },
          "bse": {
            "quantity": 0,
            "averagePrice": 0
          }
        },
        "transactableQuantity": 1,
        "smallcaseQuantity": 0,
        "nseTicker": "PNB",
        "bseTicker": "PNB",
        "isin": "INE160A01022",
        "name": "Punjab National Bank"
      }
    ],
    "updating": false,
    "lastUpdate": "2022-03-24T11:24:00.871Z",
    "snapshotDate": "2022-03-24T11:24:00.871Z",
    "smallcaseAuthId": "6195e288360acf9ebc060d23",
    "broker": "groww"
  }
}

{
  "smallcases": {
    "public": [
      {
        "scid": "SCAW_0001",
        "name": "All Weather Investing",
        "investmentDetailsURL": "https://smallcase.zerodha.com/details/5f2d22636678954954f29a2d?",
        "shortDescription": "Diversify with equity, gold & fixed income ETFs for recession-proof investing",
        "imageUrl": "https://assets.smallcase.com/images/smallcases/200/SCAW_0001.png",
        "stats": {
          "currentValue": 4921.89,
          "totalReturns": -36.65253999999927
        },
        "constituents": [
          {
            "ticker": "NIFTYBEES",
            "shares": 10
          },
          {
            "ticker": "JUNIORBEES",
            "shares": 3
          },
          {
            "ticker": "LIQUIDBEES",
            "shares": 1
          },
          {
            "ticker": "GOLDBEES",
            "shares": 39
          }
        ]
      }
    ],
    "private": {
      "stats": {
        "currentValue": 57.31,
        "totalReturns": 1.31
      }
    }
  },
  "securities": [
    {
      "holdings": {
        "quantity": 4,
        "averagePrice": 36.68
      },
      "positions": {
        "nse": {
          "quantity": 1,
          "averagePrice": 34.1
        },
        "bse": {
          "quantity": 1,
          "averagePrice": 34.1
        }
      },
      "transactableQuantity": 5,
      "smallcaseQuantity": 2,
      "nseTicker": "J&KBANK",
      "bseTicker": "J&KBANK",
      "isin": "INE168A01041",
      "name": "Jammu and Kashmir Bank Ltd"
    },
    {
      "holdings": {
        "quantity": 1,
        "averagePrice": 28.4
      },
      "positions": {
        "nse": {
          "quantity": 0,
          "averagePrice": 0
        },
        "bse": {
          "quantity": 0,
          "averagePrice": 0
        }
      },
      "transactableQuantity": 1,
      "smallcaseQuantity": 0,
      "nseTicker": "MASPTOP50",
      "bseTicker": "MASPTOP50",
      "isin": "INF769K01HP3",
      "name": "Mirae Asset S&P 500 Top 50 ETF"
    },
    {
      "holdings": {
        "quantity": 1,
        "averagePrice": 10.53
      },
      "positions": {
        "nse": {
          "quantity": 0,
          "averagePrice": 0
        },
        "bse": {
          "quantity": 0,
          "averagePrice": 0
        }
      },
      "transactableQuantity": 1,
      "smallcaseQuantity": 0,
      "nseTicker": "AXISBPSETF",
      "bseTicker": null,
      "isin": "INF846K01Z04",
      "name": "Axis AAA Bond Plus SDL ETF-2026 Matur. Reg. Growth"
    },
    {
      "holdings": {
        "quantity": 1,
        "averagePrice": 9.8
      },
      "positions": {
        "nse": {
          "quantity": 0,
          "averagePrice": 0
        },
        "bse": {
          "quantity": 0,
          "averagePrice": 0
        }
      },
      "transactableQuantity": 1,
      "smallcaseQuantity": 0,
      "nseTicker": "SUZLON",
      "bseTicker": "SUZLON",
      "isin": "INE040H01021",
      "name": "Suzlon Energy Ltd"
    },
    {
      "holdings": {
        "quantity": 1,
        "averagePrice": 48.5
      },
      "positions": {
        "nse": {
          "quantity": 0,
          "averagePrice": 0
        },
        "bse": {
          "quantity": 0,
          "averagePrice": 0
        }
      },
      "transactableQuantity": 1,
      "smallcaseQuantity": 0,
      "nseTicker": "ICICIB22",
      "bseTicker": "ICICIB22",
      "isin": "INF109KB15Y7",
      "name": "Bharat 22 ETF"
    },
    {
      "holdings": {
        "quantity": 1,
        "averagePrice": 36.05
      },
      "positions": {
        "nse": {
          "quantity": 0,
          "averagePrice": 0
        },
        "bse": {
          "quantity": 0,
          "averagePrice": 0
        }
      },
      "transactableQuantity": 1,
      "smallcaseQuantity": 0,
      "nseTicker": "PNB",
      "bseTicker": "PNB",
      "isin": "INE160A01022",
      "name": "Punjab National Bank"
    }
  ],
  "updating": false,
  "lastUpdate": "2022-03-24T11:33:52.986Z",
  "snapshotDate": "2022-03-24T11:24:00.871Z",
  "notes": "your-notes-goes-here",
  "smallcaseAuthId": "6195e288360acf9ebc060d23",
  "broker": "groww",
  "transactionId": "TRX_06726c28769e44b8920bd6eb5bbeef17",
  "timestamp": "2022-03-24T11:33:53.091Z",
  "checksum": "fe7a17d4f82831918a1363af080f5a92f382efa872b1a2a7823964b6bf7e3285"
}

Known issues 🛠

Broker-specific known data discrepancies are listed at -
https://developers.gateway.smallcase.com/page/holdings-import-v2-known-data-discrepancy

Keep reading 🔖