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


Good to know

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


Sequence diagram


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 tokenconnected user auth token - `smallcaseAuthToken` (JWT) containing `smallcaseAuthId` of the broker account with which transaction is (or, should be) performed. If such JWT is used to initialise Gateway session, SDK restricts user to allow transaction from related broker account only. Read more - https://developers.gateway.smallcase.com/discuss/61ef6d38d2a7c4000f6346be.
You can decode the JWT and get smallcaseAuthIdsmallcaseAuthId - It is an unique identifier for broker account with which user has logged in. Learn more - https://developers.gateway.smallcase.com/discuss/61ef6d38d2a7c4000f6346be 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 tokenconnected user auth token - `smallcaseAuthToken` (JWT) containing `smallcaseAuthId` of the broker account with which transaction is (or, should be) performed. If such JWT is used to initialise Gateway session, SDK restricts user to allow transaction from related broker account only. Read more - https://developers.gateway.smallcase.com/discuss/61ef6d38d2a7c4000f6346be (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).


Try holdings import

Import Holdings

Notes

  • broker support: 5Paisa, Aliceblue, Angel Broking, 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.


Did this page help you?