# Connect HSA/FSA Accounts

Your application can use Sail to retrieve HSA and FSA account data, including balances, contributions, account activity, and deposit credentials. Sail connects to the user's HSA or FSA administrator and securely retrieves this information on your behalf.

In this guide, you'll connect a user to their HSA or FSA administrator through Sail's Connect widget, retrieve their account data, and optionally access their full account and routing numbers for deposits.

## Requirements

Before you start, make sure you have:

- A [Sail user](/docs/get-started/get-started-overview/create-a-user) created for your internal user
- An [API key](/docs/get-started/get-started-overview/api-key) with the `benefit_account` scope and the `account_numbers` scope (if you need deposit credentials)
- A separate [API key](/docs/get-started/get-started-overview/api-key) with the `token_admin` scope (needed to mint user tokens for PII access and full account number reveals)

<Callout type="info" title="Note">

A `token_admin` key cannot hold other scopes, so you'll need at least two API keys: one for data access and one for minting tokens. See [Scoped API Keys](/docs/concepts/scoped-api-keys) to understand why and how to set them up.

</Callout>

## Step 1: Connect an HSA/FSA administrator

To pull account data, your user needs to log into their HSA/FSA administrator. [Create a Connect Widget session](/reference/connect-account-widgets/post-hosted-sessions) with `connection_type` set to [`benefit_account`](/docs/concepts/account-connections). Sail returns a single-use URL that you embed in your app as an iframe or redirect. The user enters their administrator credentials securely within Sail's [Connect Account Widget](/docs/concepts/connect-widget).

<Tabs>
  <Tab title="Request">

  ```bash
  curl -X POST https://live.savewithsail.com/api/v1/hosted-sessions \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "user_id": "usr_abc123",
      "flow": "connect_account",
      "options": {
        "connection_type": "benefit_account"
      }
    }'
  ```

  </Tab>
  <Tab title="Response">

  ```json
  {
    "url": "https://<HOSTED_SESSION_URL>",
    "expires_at": "2026-08-10T15:31:07Z",
    "flow": "connect_account"
  }
  ```

  </Tab>
</Tabs>

Open the `url` in an iframe or redirect your user to it. The session is single-use and the `expires_at` field tells you when it stops working. You can check which administrators Sail supports through the [List Administrators](/reference/administrators/get-administrators) endpoint.

## Step 2: Listen for webhooks

After your user completes the login, Sail connects to the administrator and discovers the user's benefit accounts. Listen for these webhook events:

| Event | What it means |
| :--- | :--- |
| `connection.created` | Your user finished the connect widget and the connection exists. |
| `connection.status_changed` | The connection moved to a new status (for example, `aggregating` to `active`). |
| `connection.synced` | Aggregation completed. The connection's data is ready to fetch. |
| `connection.synced.initial` | Initial basic account info is available. |
| `connection.synced.profile` | Account profile data has been updated. |
| `connection.synced.activity` | Account activity has been updated. |

When you receive `connection.synced`, the account data is ready to fetch. A single administrator login can hold multiple accounts (for example, an HSA and an LPFSA).

## Step 3: Confirm accounts

Once the connection is active and accounts are discovered, you can read balances, contribution progress, account activity, and deposit credentials.

[Fetch all benefit accounts](/reference/accounts/get-users-user-id-accounts) for the user. Each account includes the account type, balance, and sync status.

<Tabs>
  <Tab title="Request">

  ```bash
  curl https://live.savewithsail.com/api/v1/users/usr_abc123/accounts \
    -H "Authorization: Bearer sk_live_..."
  ```

  </Tab>
  <Tab title="Response">

  ```json
  {
    "data": [
      {
        "id": "acct_77b1",
        "connection_id": "conn_9f2c",
        "external_id": "HE-12345678",
        "name": "Health Equity HSA",
        "type": "hsa",
        "start_date": "2024-01-01",
        "end_date": null,
        "balance": {
          "cash": 1050.50,
          "invested": 500.00
        },
        "last_sync_at": "2026-08-10T14:35:00Z"
      }
    ],
    "pagination": {
      "limit": 25,
      "offset": 0,
      "total": 1
    }
  }
  ```

  </Tab>
</Tabs>

Amounts are decimal numbers in USD (for example, `1050.50` means $1,050.50). The connection is now active and you can start reading account data.