> ## 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**    | Expires after 8 minutes of inactivity during authorization, or 30 minutes during data processing |
| **Reusability** | Cannot be reused — generate a new one for each session                                           |
| **Purpose**     | Grants access to data endpoints like `/GetAccountsDetail` and `/GetStatements`                   |

<Warning>
  A `requestId` cannot be reused. Once a session expires or completes, you must call `/Authorize` again to generate a new `requestId`.
</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.