> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flinks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Key Concepts

> Understand the core concepts of the Flinks API: LoginId, RequestId, caching, and transaction types.

## LoginId vs RequestId

Flinks uses two key identifiers to manage account connections and data retrieval sessions.

### LoginId

A `loginId` is a **permanent token** issued when a customer successfully authenticates through Flinks Connect. It represents the saved connection to a specific financial institution account.

| Property        | Detail                                                                                                      |
| :-------------- | :---------------------------------------------------------------------------------------------------------- |
| **Lifetime**    | Permanent, does not expire until you call [/DeleteCard](/api/connect/endpoints/account-linking/delete-card) |
| **Uniqueness**  | Tied to a specific institution, username, and language                                                      |
| **Persistence** | Remains the same even if the customer's banking password changes                                            |
| **Scope**       | Unique per instance (e.g., sandbox vs. production)                                                          |
| **Storage**     | Store securely on your servers, never expose publicly                                                       |

The `loginId` stores the customer's credentials, KYC data, and linked accounts. Flinks retains this data indefinitely unless you explicitly delete it with `/DeleteCard`.

### RequestId

A `requestId` is a **session token** generated each time you call the [/Authorize](/api/authorize/endpoints/authorize) endpoint with a `loginId`.

| Property             | Detail                                                                                                                                     |
| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| **Lifetime**         | Ends on timeout (8 minutes of inactivity during authorization, or 30 minutes during data processing) or when a completing call consumes it |
| **Completing calls** | `/GetAccountsDetail`, `/GetAccountsDetailAsync`, and `/GetStatements` complete the session and consume the `requestId`                     |
| **Reusable calls**   | `/GetAccountsSummary` and the Attributes endpoints do not complete the session, so one `requestId` can call multiple Attributes packages   |
| **Purpose**          | Grants access to data endpoints like `/GetAccountsDetail` and `/GetStatements`                                                             |

<Warning>
  A `requestId` ends in one of two ways: the session times out, or a completing call (`/GetAccountsDetail`, `/GetAccountsDetailAsync`, or `/GetStatements`) consumes it. After either, call `/Authorize` again for a new `requestId`. In cached mode (`MostRecentCached: true`), a cached `requestId` is not consumed by cached `/GetAccountsDetail`, so you can reuse it for cached GAD and multiple Attributes calls.
</Warning>

### Typical flow

```mermaid theme={null}
flowchart LR
    A["loginId<br/>(permanent)"] -->|"/Authorize"| B["requestId<br/>(session)"]
    B -->|"/GetAccountsDetail"| C["Financial Data"]
```

## Instances

A Flinks instance is regionally scoped: each instance is hosted in a specific country (Canada or the U.S.) and serves only that country's end-users. If you onboard customers in both countries, you'll be provisioned with two separate instances, one per country, each with its own credentials, base URLs, and `customerId`.

For full details, see [Instances and Data Residency](./instances).

## Cached mode

When calling the `/Authorize` endpoint, use `MostRecentCached: true` to retrieve the most recently processed data without initiating a new live connection to the financial institution.

**When to use cached mode:**

* Retrieving data that was already collected (e.g., for Attributes processing)
* Opening a session to access stored data without requiring the customer to re-authenticate
* Daily refresh routines where Nightly Refresh has already collected fresh data

**When NOT to use cached mode:**

* When you need a fresh, live connection to the financial institution
* When performing a manual refresh (use `MostRecentCached: false` with `Save: true`)

## Post vs Pending transactions

The Flinks API returns **posted transactions only**: transactions that have been fully processed by the financial institution.

<Note>
  Pending transactions (transactions that have been initiated but not yet settled) are not included in the API response. However, the **Available Balance** on an account may reflect pending transactions, which is why it can differ from the **Current Balance**.
</Note>

## Data retention

Flinks retains all data associated with a `loginId` indefinitely. If you need to delete a customer's data:

1. Call the [/DeleteCard](/api/connect/endpoints/account-linking/delete-card) endpoint with the `loginId`.
2. This permanently removes all stored credentials, KYC information, and account data.
3. The `loginId` becomes invalid and cannot be reused.