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 created for your internal user
An API key with the benefit_account scope and the account_numbers scope (if you need deposit credentials)
A separate API key with the token_admin scope (needed to mint user tokens for PII access and full account number reveals)

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 to understand why and how to set them up.

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 with connection_type set to benefit_account. 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.

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"
    }
  }'

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

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 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 for the user. Each account includes the account type, balance, and sync status.

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

{
  "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
  }
}

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.