Skip to main content
The standard integration is the most common way to connect with Flinks. It pairs the Flinks Connect iframe on the front end with API requests on the back end. This page walks through the full happy-path flow, from launching the iframe to retrieving account data.

​
Front end vs. back end

Every Flinks integration has two independent halves. You choose one option for each. The Client Dashboard is a self-serve UI that calls the back end on your behalf, not a separate back-end option.
This page describes the standard integration: Flinks Connect on the front end plus API requests on the back end. If you want data pushed to you automatically instead of polling, see Choosing your back end below.

​
Prerequisites

Before you begin, make sure you have the following credentials and values. You can find these in your Flinks Dashboard or from your Flinks representative.
ValuePurpose
Customer ID (customerId)Identifies your account. Used in every API URL path.
Instance nameYour regionally-scoped instance (for example, sandbox vs. production). Determines your base URLs. See Instances.
Secret keyThe unique key Flinks provides during integration. Passed in the flinks-auth-key header of /GenerateAuthorizeToken to create authorize tokens.
Authorize tokenA single-use token generated from your secret key. Passed to Flinks Connect (URL parameter) or to /Authorize (flinks-auth-key header).
iframe base URLThe Flinks Connect endpoint you launch, in the form https://yourinstance-iframe.private.fin.ag/.
The secret key and the authorize token are not the same. Use the secret key only to generate authorize tokens; use the authorize token to authenticate Flinks Connect or /Authorize. See Set Up Authorization.

​
End-to-end flow

The diagram below shows the standard integration happy path.

​
Step-by-step

1

Generate an authorize token to launch the iframe

Call /GenerateAuthorizeToken with your secret key in the flinks-auth-key header.
  • Input: secret key (header)
  • Output: an authorize token that is single-use and active for 15 minutes.
Pass this token to Flinks Connect using the authorizeToken URL parameter:
URL
https://yourinstance-iframe.private.fin.ag/?redirectUrl=flinks.com&authorizeToken=d65f1adb-8ebc-48dc-be8b-20c773ba1565
2

The end user completes Flinks Connect

The end user selects their financial institution, enters their credentials, and completes multi-factor authentication (MFA) if their bank requires it. Flinks Connect handles all bank processes, edge cases, and errors on your behalf.When the connection succeeds, capture the loginId (and optionally an accountId) from the Flinks Connect event listener or the redirect URL.
  • Output: loginId, a permanent token representing the saved connection. Store it securely on your servers; never expose it publicly.
The loginId does not expire and is required for all future data retrieval. See Key Concepts.
3

Generate a fresh authorize token

The token you generated in step 1 was consumed when you launched Flinks Connect. Authorize tokens are single-use, so call /GenerateAuthorizeToken again to create a new token before calling /Authorize.
  • Input: secret key (header)
  • Output: a fresh authorize token.
Generate a fresh authorize token continuously across the session, any time you are about to make a call that requires one. Reusing a consumed token will fail authentication.
4

Call /Authorize in cached mode

Call /Authorize with the loginId, passing the fresh authorize token in the flinks-auth-key header. Use cached mode (MostRecentCached: true) to open a session against the data that was just collected.
Authorize
curl --request POST \
  --url https://yourinstance-api.private.fin.ag/v3/{customerId}/BankingServices/Authorize \
  --header 'Content-Type: application/json' \
  --header 'flinks-auth-key: {authorize_token}' \
  --data '{
    "LoginId": "your-login-id",
    "MostRecentCached": true
  }'
In cached mode the response is 200, because the end user already completed any required authentication in the iframe.
  • 200: Authenticated. Use the returned RequestId to retrieve data (next step).
  • Output: a RequestId, a session token used to call the data endpoints. It cannot be reused.
5

Retrieve account data

Send a POST request to /GetAccountsDetail with the RequestId in the body. (Use /GetAccountsSummary if you only need summary-level data.)Handle the response by status:
  • 200: Data is ready. The response contains the full account payload.
  • 202: The operation is still processing. Poll for the result (next step). A 202 is expected on the initial call.
6

Poll on 202 until data is ready

When /GetAccountsDetail returns 202:
  1. Call /GetAccountsDetailAsync with the same RequestId as a path parameter (this is a GET request).
  2. If the response is 202, the data is still processing. Wait ~10 seconds, then poll again.
  3. Repeat until you receive a 200, which contains the same payload as a 200 from /GetAccountsDetail.
  4. Set a maximum timeout of 30 minutes to avoid an infinite polling loop.
/GetAccountsDetailAsync is not a separate data endpoint. It is the polling mechanism for /GetAccountsDetail. See Retrieve Account Data.
7

(Optional) Enrich the data with Attributes

If your use case needs enriched insights, call the Attributes / Enrich endpoint on demand with the RequestId.
Attributes are fetched on demand by making an API request. They are not returned automatically with account data and are not delivered by webhook.

​
Choosing your back end

This page uses API requests with polling on the back end. If you would rather have data pushed to you automatically when processing completes, without writing polling logic, set up Webhooks instead. For a side-by-side comparison of API requests vs. Webhooks, see Choose a Back-End Solution.

​
Next steps

Set Up Authorization

Generate and pass authorize tokens correctly.

Retrieve Account Data

Full detail on the data retrieval and polling flow.

Handled Errors

Understand how Flinks reports and handles errors.

Resume and Reconnect

Re-establish a connection for a returning user.

Webhooks

Receive data automatically instead of polling.