> ## 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.

# Upload Integration Tips

> Integration modes, fallback triggers, and best practices for Flinks Upload.

This guide covers practical tips for integrating Flinks Upload into your application, including submission modes, data consumption patterns, and handling edge cases.

## Integration modes for submitting documents

There are three ways users can submit documents to Flinks Upload:

| Mode                          | Description                                                                | Best for                                                     |
| :---------------------------- | :------------------------------------------------------------------------- | :----------------------------------------------------------- |
| **Connect Widget (Primary)**  | Upload option displayed alongside bank linking after institution selection | Maximum coverage — users choose between linking or uploading |
| **Connect Widget (Fallback)** | Upload option appears only after a failed bank login attempt               | Keeping bank linking as the primary flow                     |
| **Dashboard**                 | Manual upload through the Flinks Dashboard                                 | Back-office or support-initiated uploads                     |

For details on configuring the primary and fallback modes, see [Flinks Upload](/guides/upload/flinks-upload).

## Integration modes for consuming data

| Mode          | Description                                                                                                                                                 |
| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**       | Call [`/GetAccountsDetail`](/api/connect/endpoints/account-linking/get-accounts-detail) to retrieve extracted transaction and account data programmatically |
| **Dashboard** | View extracted data and fraud signals visually in the Flinks Dashboard                                                                                      |

Use the API for automated workflows. Use the Dashboard for manual review of fraud signals and document quality.

## Fallback triggers

When Upload is configured as a fallback in Flinks Connect, the upload option appears automatically when the user encounters one of these connection errors:

| Error code                           | Description                                                  |
| :----------------------------------- | :----------------------------------------------------------- |
| `INVALID_USERNAME`                   | The username entered was not recognized                      |
| `INVALID_PASSWORD`                   | The password entered was incorrect                           |
| `INVALID_LOGIN`                      | Generic login failure                                        |
| `DISABLED_LOGIN`                     | The user's online banking access is disabled                 |
| `RETRY_LATER`                        | The financial institution is temporarily unavailable         |
| `SESSION_EXPIRED`                    | The session timed out during authentication                  |
| `INVALID_SECURITY_RESPONSE_NO_RETRY` | Security question answered incorrectly with no retry allowed |
| `AGGREGATION_ERROR`                  | A general error occurred during data aggregation             |

The fallback behavior is also built into the Primary configuration — so if you enable Primary mode, fallback logic is included automatically.

## Force-upload shortcut

You can send users directly to the upload flow for a specific financial institution by appending `/upload/[Institution Name]` to your Flinks Connect URL:

```url theme={null}
https://[instance]-iframe.private.fin.ag/v2/upload/[Institution Name]
```

This bypasses the institution selector and login screens, taking the user straight to the document upload screen for the specified institution.

## Async handling with webhooks

Flinks Upload processes documents asynchronously. Rather than polling the API for results, configure [webhooks](/guides/webhooks/introduction) to receive a notification when processing completes.

<Tip>
  **Use webhooks over polling.** Webhook-based async handling is the recommended pattern for Upload. It reduces unnecessary API calls and delivers results as soon as they're ready.
</Tip>

## Credit union member numbers

For credit union accounts, member numbers may be displayed with suffixes that indicate the account type:

| Suffix           | Account type           |
| :--------------- | :--------------------- |
| `-0`             | Chequing / share draft |
| `-1`             | Savings                |
| `-2`, `-3`, etc. | Additional accounts    |

For example, a member number like `xxxx2354-0` indicates a chequing account, while `xxxx2354-1` indicates a savings account under the same membership.

## Multiple files in one upload

When a user uploads multiple PDF files in a single submission, they count as **one upload** against your quota. You don't need to have users submit files one at a time — up to 24 files (180 MB total) can be included in a single upload.

## Related resources

* [Getting Started with Upload](/guides/upload/getting-started)
* [Flinks Upload](/guides/upload/flinks-upload)
* [Upload Capabilities](/guides/upload/capabilities)
* [Webhooks](/guides/webhooks/introduction)