What Is the Connect HSA/FSA API?

The Connect HSA/FSA API connects your end user to the institution that holds their health savings or flexible spending money, and gives your backend read access to what's in it, including balances, plan dates, account activity, contribution progress, and, when you need them, the full account and routing numbers for a deposit.

What each HSA/FSA carries

Once a user connects their administrator, Sail discovers the accounts behind that login and keeps them in sync. Each Account carries:

The account name and type, one of hsa, fsa, dcfsa, lpfsa, or hra.
balance, split into cash and invested, as decimal numbers in USD (for example, 1050.50 means $1,050.50). invested is 0 for an FSA and its variants.
start_date, and end_date for plan-bound accounts such as an FSA. end_date is null for an HSA, which has no plan-year end.
last_sync_at, so you know how fresh the numbers are.

Account activity and contribution progress against IRS limits are available on their own endpoints, and masked account and routing numbers are available for setting up deposits.

How it works

Connecting an account takes three steps:

Your end user logs into their HSA/FSA administrator inside Sail's Connect Account Widget. Their administrator credentials are entered only inside Sail's iframe, so they never touch your servers.
Sail connects to the administrator and discovers the accounts behind that login. One login can hold more than one account, for example an HSA and a limited-purpose FSA.
Your backend reads balances and activity from the API, and Sail sends a webhook whenever any of it changes.

The Read an HSA/FSA Balance quickstart walks through all three.

Reading deposit credentials

Moving money into a user's HSA/FSA requires the full account and routing numbers. Those are personally identifiable information, so Sail asks for a second credential before returning them. Alongside your API key, you need to send an ephemeral user token minted with a token_admin key.

📘
On live keys, token_admin is exclusive and can't be combined with other scopes, so an integration that reveals full numbers needs at least two keys. One holds benefit_account and account_numbers for the data, and a separate one holds token_admin for minting tokens. See Scoped API Keys.

If you only need to display the account to a user, masked numbers are enough. Those still need the account_numbers scope and a user token, but the token doesn't need the numbers:reveal scope.

Who it's for

The Connect HSA/FSA API fits an application that needs to show a user what's in their benefit account, or needs the routing details to move money into it. Choose it if:

You want to show users their HSA/FSA balance, contributions, and account activity.
You need the deposit account and routing numbers for a user's HSA/FSA.
You build a healthcare benefits, personal finance, or tax planning product.

It's the product that makes reimbursement possible, since a reimbursement draws from a linked account. It doesn't require one, though. Reading balances and activity is useful on its own.

Next steps

To connect an administrator and read your first balance, see the Read an HSA/FSA Balance quickstart.
To see the full integration, including deposit credentials, see Connect a User's HSA/FSA.
To pay a user back from a linked account, see Reimbursement.