Start to Retrieve Investments Data

Install Flinks Connect

Users of this guide should be familiar with the basic mechanics of Flinks' data connectivity, including how to configure and install Flinks connect.

Displaying Investment institutions on Flinks Connect will be enabled automatically in your environment by Flinks.

This will display only those institutions where it is possible to retrieve Investments data and will hide any financial institutions where this data type is not available. Should you need a separate instance for testing this functionality we will provision a new instance for you.

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.

API Requests Flow to pull back /Investments Data

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.

1. Initiating a Session with Flinks API

This is the first API request that needs to be executed whenever 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:

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:

{
    "Links": [
        {
            "rel": "InvestmentsDetail",
            "href": "/Investments",
            "example": null
        }
    ],
    "HttpStatusCode": 200,
    "Login": {
        "Username": "[email protected]",
        "IsScheduledRefresh": false,
        "LastRefresh": "2020-09-23T17:26:19.7050856",
        "Type": null,
        "Id": "4500022b-69be-4481-beee-08d845f8da3d"
    },
    "Institution": {
        "Id": 999999999,
        "Name": "FlinksInvestment"
    },
    "RequestId": "e705e4d8-e7e8-4e17-ab5c-802fd6a52188"
}

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 retrieve Investments data.

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:

curl -X POST \
  https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/Investments \
  -H 'Content-Type: application/json' \
  -d '{
  "LoginId":"5e115eac-1209-4f19-641c-08d6d484e2fe",
	"RequestId":"1243c283-e0ca-4fda-a5e4-343068430190"
  "MostRecentCached": true
}'

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:

{
    "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.

❗️

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're 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 below.