Skip to main content
Users of this guide should be familiar with the basic mechanics of Flinks data connectivity, including how to Set up Flinks connect. Displaying Investment institutions on Flinks Connect will be enabled automatically in your environment by Flinks. The system filters the list to display only financial institutions from which Investment data can be retrieved. Should a dedicated environment be required for testing this functionality, we can provision a new instance upon request .

​
Make API calls

Anytime you want to access your user’s financial data, you will need to use the LoginId associated with that user’s account to make a request to our API. Here is a step by step overview of this process:
  1. A successful connection redirects the user to the landing page of your choice. At this moment, a LoginId is issued and sent from your client-side to your server.
  2. When you initiate an API call, the LoginId is exchanged for a RequestId with the Flinks API and a session is initiated.
  3. Once a session is active, you can request for data and receive it. If you place a request while a session is loading, it may return an error. If this happens, retry after the session finishes loading.

​
Pulling back /Investments data with the API Requests Flow

Okay, let’s dig deeper into how exactly you can retrieve financial data from connected accounts. In order to do that, your server needs to perform a series of API requests. This is the first API request that needs to be executed when you want to retrieve data from a connected account. Flinks API needs to confirm the validity of the request and to know from which account you want to retrieve data. To do so, you will exchange your LoginId for a new RequestId. For that, the /Authorize endpoint needs to be called using a POST method, and it requires a loginId and the parameter MostRecentCached: true. To make it more concrete, let’s suppose that you are opening a new session to retrieve the data for the LoginId: 5e115eac-1209-4f19-641c-08d6d484e2fe:
Json

    curl -X POST \
      https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/Authorize \
      -H 'Content-Type: application/json' \
      -d '{
    	"LoginId":"5e115eac-1209-4f19-641c-08d6d484e2fe",
    	"MostRecentCached":true
    }'
This is how your response will look like:
Json
{
    "Links": [...],
    "HttpStatusCode": 200,
    "Login": {
        "Username": "Greatday",
        "IsScheduledRefresh": false,
        "LastRefresh": "2019-05-09T13:47:46.5227901",
        "Type": "Personal",
        "Id": "5e115eac-1209-4f19-641c-08d6d484e2fe"
    },
    "Institution": "FlinksCapital",
    "RequestId": "1243c283-e0ca-4fda-a5e4-343068430190"
}
The LoginId (5e115eac-1209-4f19-641c-08d6d484e2fe) was successfully exchanged for a RequestId (1243c283-e0ca-4fda-a5e4-343068430190). Now that the session is active, we have everything we need to place a call to retrieveInvestmentsdata.

​
2. Requesting Ready-to-Deliver data

The next step is for your server to send a request for data. This request uses the /Investments endpoint, which also needs to be made using a POST method, and requires the acquired RequestId, the previously used LoginId and the parameter MostRecentCached:true. Continuing our example using our RequestId (1243c283-e0ca-4fda-a5e4-343068430190), it looks like this:
Json
     curl -X POST \
      https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/GetAccountsDetail \
      -H 'Content-Type: application/json' \
      -d '{
    	"RequestId":"1243c283-e0ca-4fda-a5e4-343068430190"
    }'
The most common first response to get in a request for data returns an HTTP 202 FlinksCode: OPERATION_PENDING, meaning that the data you are requesting is still being processed. Here’s an example of a typical API response for data pending processing:
Json
    				{
        "FlinksCode": "OPERATION_PENDING",
        "Links": [...],
        "HttpStatusCode": 202,
        "Message": "Your operation is still processing",
        "RequestId": "1243c283-e0ca-4fda-a5e4-343068430190"
    }
Because of this, your server needs to expect and be able to handle this response and proceed to poll the request (link to async poll code samples) to receive the data, which is described in the next step.
When sending requests for data…Your integration must handle the 202 OPERATION_PENDING response.

​
3. Requesting Pending-to-Deliver data

While you receive the response HTTP 202 FlinksCode: OPERATION_PENDING, you need to keep calling the /Investments endpoint (with the same parameters above) every 10 seconds for a maximum of 30 minutes.
If you are still receiving 202 OPERATION_PENDING...In case your data is still pending, you need to call this endpoint every 10 seconds for a maximum of 30 minutes. This doesn’t mean that your request is going to take that long, but this global timeout is required to avoid infinite loops.
Once your data is done being processed, the API will respond with an HTTP 200 and a JSON payload containing all the data we collected from the investment account in a standard format. Your app server will be ready to start handling it according to your use-case. For a full detailed breakdown of the /Investments call and response fields, please refer to the documentation on the /Investments API page. The /Investments endpoint gives Flinks’ clients the ability to retrieve user-permissioned data on wealth or investment (terms which here can be used interchangeably) holdings across a number of different assets, classes, and institutions. The product’s architecture is fundamentally based on our retail banking data aggregation response; however, it incorporates several novel concepts unique to this dataset. Here are some of those key new concepts in action, which will all be explored in depth later in this guide:
  • Institution: the financial institution where the investment accounts exist
  • Accounts: the places where investment activity occurs
  • Positions: a point-in-time snapshot of the investment portfolio
  • Securities: the details of the assets within the current or past positions
  • Transactions: the historical activities that built the current portfolio