Holdings Import

Build a holistic view of a userโ€™s equity investments ๐Ÿ“Š๐Ÿ“ˆ๐Ÿ“‰

With smallcase Gateway, you can easily import the latest snapshot of a userโ€™s stock, ETF and smallcase holdings, upon one-time user consent.

Using holdings data will help you build a holistic view of a user's equity investments.

How it works

11001100

Good to know

To continue, we recommend reading following sections of the Getting Started guide:


Sequence diagram

12171217
12291229

import holdings and subsequently refresh holdings


Integration details

Step 1: Create a transaction on your server

When a user intends to import holdings, a transactionId has to be created for the SDK interaction.
Use create holdings import transaction API on your server to create and fetch a unique transactionId.

Step 2: Integrate Gateway SDK on client-side

2.1 Initialise gateway session

Use a relevant guest / connected auth token to initialise the gateway session.

Learn more about initialising the gateway session in respective SDK integration page.

2.2 Pass transactionId to trigger transaction method

Next, pass the holdings import transactionId (generated in step 1) to SDK's trigger transaction method. Gateway SDK will now show relevant screens (broker chooser, broker login, import authorisation, etc) to the user. Once done, the user's latest holdings snapshot is saved in the smallcase system.

Step 3: Handle response on client or server

3.1 From SDK response (client-side)

Trigger transaction will respond with a connected user auth token.
You can decode the JWT and get smallcaseAuthId of the linked broker account.
More in the next step.

OR

3.2 Using webhook/postback (server-side)

Optionally, you can register a holdings import webhook for your gateway.
If done, every time a user import their holdings on the client-side, smallcase Gateway systems will hit your registered webhook with the user's holdings data, transactionId, smallcaseAuthId. The data should be saved against the relevant user in your systems on every webhook hit.

Step 4: Fetch holdings from your server

On getting success confirmation from the trigger transaction method, you can fetch relevant holdings of the user from your server.

If, not using webhook

Fetch holdings API should be called from your server by passing relevant connected user auth token (recall: SDK shares this in step 3.1).

Else if, using webhook

Your server can simply pull holdings data (recall: this data was saved in the database at step 3.2).


Demo: Try holdings import

Try demo on smartinvesting.io

Response Structure

Holdings data can be consumed in two ways:

  1. Fetch holdings API
    This API requires connected user auth token which can be consumed from SDK's transaction success response or fetch transaction details
  2. Holdings import webhook/postback

Holdings v2 response structure and response is available in Holdings Import v2 ๐Ÿ“ƒ guide


Notes

  • broker support: 5Paisa, Angel Broking, Dhan, Groww, IIFL, Motilal Oswal, Trustline, Upstox & Zerodha

  • session-based holdings refresh: Most brokers (all except Zerodha) require client-side broker login to update the holdings data (i.e. latest snapshot). Hence, a HOLDINGS_IMPORT transaction has to be triggered via SDK to refresh the user's holdings, each time user places an order directly from their broker's terminal.

  • session-less holdings refresh: For supported brokers (Zerodha), directly calling fetch user holdings API will ensure that holdings snapshot is updated on-the-fly. The user will still have to authorise holdings for the first time.


Next steps