Make API Calls

So far, we have covered how to embed a Flinks Connect iframe in your client-side application and use it to connect to bank accounts. This section will guide you through the process of exchanging loginId to requestId and actually retrieve the financial data.

Overview

Anytime you want to access you user's financial data, you will need to use the loginId associated to 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 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

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.

📘

If you are still not sure how to perform these API calls and would like more help, head over to our Flinks API Reference for more details.

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 which account you want to retrieve data from. 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": [...],
    "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 retrieve financial data.

2. Requesting Ready-to-Deliver Data

The next step is for your server to send a request for data. This request uses the /GetAccountsDetail endpoint, which also needs to be made using a POST method, and only requires the acquired requestId.

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/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 a 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 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

For requests that are still pending for data processing, only the requestId is needed, but the parameter goes directly into the API URL as it's a GET request.

While you receive the response HTTP 202 FlinksCode: OPERATION_PENDING, you need to keep calling this endpoint every 10 seconds for maximum of 30 minutes.

curl -X GET \
  https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/BankingServices/GetAccountsDetailAsync/1243c283-e0ca-4fda-a5e4-343068430190 \
  -H 'Content-Type: application/json'

❗️

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 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 a HTTP 200 and a JSON payload containing all the data we collected from the financial institution in a standard format. Your app server will be ready to start handling it according to your use-case.

{
    "HttpStatusCode": 200,
    "Accounts": [
        {
            "Transactions": [
                {
                    "Date": "2019-04-22",
                    "Code": null,
                    "Description": "national money",
                    "Debit": 12.08,
                    "Credit": null,
                    "Balance": 49993.96,
                    "Id": "633b976e-c713-4b59-9717-3ec407bdde8b"
                },
                {
                    "Date": "2019-04-21",
                    "Code": null,
                    "Description": "[email protected]",
                    "Debit": null,
                    "Credit": 12.07,
                    "Balance": 50006.04,
                    "Id": "ac25ab22-2828-4174-9653-23bb8918b7c4"
                }
            ],
            "TransitNumber": "77777",
            "InstitutionNumber": "777",
            "OverdraftLimit": 0,
            "Title": "Chequing CAD",
            "AccountNumber": "1111000",
            "Balance": {
                "Available": null,
                "Current": 49993.96,
                "Limit": null
            },
            "Category": "Operations",
            "Type": "Chequing",
            "Currency": "CAD",
            "Holder": {
                "Name": "John Doe",
                "Address": {
                    "CivicAddress": "1275 avenue des Canadiens-de-Montréal",
                    "City": "Montréal",
                    "Province": "QC",
                    "PostalCode": "H3B 5E8",
                    "POBox": null,
                    "Country": "CA"
                },
                "Email": "[email protected]",
                "PhoneNumber": "(514) 333-7777"
            },
            "Id": "ae1dac72-70da-4626-fed8-08d682e1ff4a"
        },
        {...}      
    ],
    "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"
}

Checklist

Before moving on, let's review what we just did:

👍

Mastering the API Calls Flow

• Receive a new requestId with incoming loginId by calling /Authorize with MostRecentCached:true

• Request ready-to-deliver data with /GetAccountsDetail and handle 202 OPERATION_PENDING responses

• Request pending-to-deliver data with /GetAccountsDetailAsync for previous 202 OPERATION_PENDING responses