Changelog
< Back to Flinks

Set up API Calls

Set up the correct API calls to retrieve investment data.

Suggest Edits

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. as well as the previous page in this guide that details all supported parameters for Investments.

Flinks Connect handles account connections to both retail banking and investments institutions. To ensure your end users have a simple and intuitive experience, Flinks Connect displays only one set of institutions at a time.

🚧

It may be time to chat!

Flinks' Investments must be enabled at your request before investment institutions can be displayed in your environment.

Make sure you speak to your Account Manager or reach out to [email protected] so we can get you set up!

While testing on our Sandbox Environment, use the Flinks Connect URL parameters productType=investment or productType=Banking to switch between the two institution displays.

❗️

Flinks Connect URL Parameters

The parameters productType=Banking or productType=investment will only work when Investments is enabled on your instance. Please reach out to [email protected] if Investments is not enabled.

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.

Retrieve /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 the 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": "5e115eac-1209-4f19-641c-08d6d484e2fe"
    },
    "Institution": {
        "Id": 999999999,
        "Name": "FlinksInvestment"
    },
    "RequestId": "e705e4d8-e7e8-4e17-ab5c-802fd6a52188"
}

The loginId (5e115eac-1209-4f19-641c-08d6d484e2fe) was successfully exchanged for a requestid (e705e4d8-e7e8-4e17-ab5c-802fd6a52188). 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 (e705e4d8-e7e8-4e17-ab5c-802fd6a52188), it looks like this:

curl -X POST \
  https://toolbox-api.private.fin.ag/v3/43387ca6-0391-4c82-857d-70d95f087ecb/Investments \
  -H 'Content-Type: application/json' \
  -d '{
  "LoginId":"5e115eac-1209-4f19-641c-08d6d484e2fe",
	"RequestId":"e705e4d8-e7e8-4e17-ab5c-802fd6a52188"
  "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": "e705e4d8-e7e8-4e17-ab5c-802fd6a52188"
}

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.

/Investments Endpoint Response

What follows is a standard HTTP 200 JSON payload from the /Investments endpoint.

{
    "Accounts": [
        {
            "Id": "500efd20-8643-49f1-b61c-08d845f8e6df",
          	"FullAccountId": "non-registered-123456:cash:cad",
          	"AccountId": "123456"
            "Name": "Random Investment",
            "Type": "cash",
            "Registered": false,
            "Currency": "CAD",
            "Cash": 100.00,
            "AccountValue": 16.32,
            "CurrencyValue": 16.32,
            "Positions": [
                {
                    "Id": "b2ee340f-051b-4fd9-db14-08d845f8e6e0",
                    "Category": "Canadian Stocks",
                    "Class": "equity",
                    "BookValue": 600.00,
                    "Quantity": 120,
                    "MarketValue": 549.60,
                    "GainAmount": -50.40,
                    "GainCurrencyAmount": -50.40,
                    "GainPercent": -0.08,
                    "Currency": "CAD",
                    "SecurityId": "de7539cf-6814-4f24-993b-20f54b860b6d"
                },
                {
                    "Id": "cc71388b-2055-41a6-db15-08d845f8e6e0",
                    "Category": "US Stocks",
                    "Class": "equity",
                    "BookValue": 600.00,
                    "Quantity": 6,
                    "MarketValue": 599.94,
                    "GainAmount": -0.06,
                    "GainCurrencyAmount": -0.06,
                    "GainPercent": 0.00,
                    "Currency": "CAD",
                    "SecurityId": "1f4ccbe8-2eae-43f4-9d94-a054f90e5197"
                },
                {
                    "Id": "ca2ba9c4-f133-47f0-db16-08d845f8e6e0",
                    "Category": "US Stocks",
                    "Class": "equity",
                    "BookValue": 600.00,
                    "Quantity": 1,
                    "MarketValue": 555.87,
                    "GainAmount": -44.13,
                    "GainCurrencyAmount": -44.13,
                    "GainPercent": -0.07,
                    "Currency": "CAD",
                    "SecurityId": "74d8129e-52ab-4f0b-9b9e-eaa5e047a187"
                }
            ],
            "Transactions": [
                {
                    "Id": "0e76c626-5771-4277-6c06-08d845f8e6e6",
                    "Date": "2020-07-31",
                    "Type": "sell",
                    "Description": "Sell 3 AAPL on last day of the month",
                    "Quantity": -3,
                    "Fee": 0.00,
                    "Amount": 400.00,
                    "SecurityId": "1f4ccbe8-2eae-43f4-9d94-a054f90e5197"
                },
                {
                    "Id": "366f3864-01d9-45d2-6c07-08d845f8e6e6",
                    "Date": "2020-08-01",
                    "Type": "buy",
                    "Description": "Buy 3 AAPL on first day of the month",
                    "Quantity": 3,
                    "Fee": 0.00,
                    "Amount": -300.00,
                    "SecurityId": "1f4ccbe8-2eae-43f4-9d94-a054f90e5197"
                },
                {
                    "Id": "307afa6b-4aad-4f76-52b0-08d85f231bb7",
                    "Date": "2020-08-31",
                    "Type": "sell",
                    "Description": "Sell 3 AAPL on last day of the month",
                    "Quantity": -3,
                    "Fee": 0.00,
                    "Amount": 400.00,
                    "SecurityId": "fcc50cd6-3de8-4bae-913f-e9d313963c70"
                },
                {
                    "Id": "bdbf333e-b08e-4998-52b1-08d85f231bb7",
                    "Date": "2020-09-01",
                    "Type": "buy",
                    "Description": "Buy 3 AAPL on first day of the month",
                    "Quantity": 3,
                    "Fee": 0.00,
                    "Amount": -300.00,
                    "SecurityId": "fcc50cd6-3de8-4bae-913f-e9d313963c70"
                }
            ]
        },
        {
            "Id": "8f43bf1d-6bfe-492f-b61d-08d845f8e6df",
           	"FullAccountId": "non-registered-654321:cash:usd",
          	"AccountId": "654321"
            "Name": "Uncle Sam",
            "Type": "cash",
            "Registered": false,
            "Currency": "USD",
            "Cash": 100.00,
            "AccountValue": 132.93,
            "CurrencyValue": 100.00,
            "Positions": null,
            "Transactions": null
        }
    ],
    "Securities": [
        {
            "Id": "6b48f77c-1ad1-477f-9cbd-dedbe089a8e3",
            "Name": "BlackBerry Ltd",
            "Symbol": "BB.DEMO",
            "Type": "equity",
            "Price": 4.34,
            "Date": "2020-09-21T22:07:24.2480000Z",
            "Aliases": [
                "BlackBerry Ltd"
            ],
            "Currency": "CAD",
          	"CUSIP": "09228F",
          	"ISIN": null,
        },
        {
            "Id": "fcc50cd6-3de8-4bae-913f-e9d313963c70",
            "Name": "Apple Inc.",
            "Symbol": "AAPL.DEMO",
            "Type": "equity",
            "Price": 62.23,
            "Date": "2020-09-21T22:07:24.2370000Z",
            "Aliases": [
                "Apple Inc."
            ],
            "Currency": "USD",
          	"CUSIP": "037833100",
          	"ISIN": "US0378331005"
        },
        {
            "Id": "f6ab80f8-af7a-4b8e-a8bc-6639d5939edc",
            "Name": "Google Inc",
            "Symbol": "GOOGL.DEMO",
            "Type": "equity",
            "Price": 336.37,
            "Date": "2020-09-21T22:07:24.2240000Z",
            "Aliases": [
                "Google Inc"
            ],
            "Currency": "USD"
          	"CUSIP": "02079K305"
          	"ISIN": null,
        }
    ],
    "Value": 149.25,
    "Cash": 232.93,
    "HttpStatusCode": 200,
    "Login": {
        "Username": "[email protected]",
        "IsScheduledRefresh": false,
        "LastRefresh": "2020-09-22T18:12:45.9357137",
        "Type": null,
        "Id": "4500022b-69be-4481-beee-08d845f8da3d"
    },
    "Institution": {
        "Id": 999999999,
        "Name": "FlinksInvestment"
    },
    "RequestId": "e705e4d8-e7e8-4e17-ab5c-802fd6a52188"
}

Updated 5 months ago

What’s Next

Now that you've set up to call and received data from the /Investments endpoint, let's see if you're ready to go to production!