# Account Connections

Sail connects to three kinds of accounts:

* Bank and card accounts
* Merchant accounts
* HSA/FSA administrator accounts

All three are established the same way, through a `connect_account` flow of the [Connect Account Widget](/docs/concepts/connect-widget), but each produces different data. The table below describes each connection type and what it gives you.

| Connection type (`connection_type`) | Links to | Produces |
| :--- | :--- | :--- |
| `card` | A bank or credit/debit card | Transaction-level expenses |
| `store` | A merchant account | Item-level expenses |
| `benefit_account` | An HSA/FSA administrator | Account information |

A fourth connection type, `external`, isn't established through the Connect Account Widget at all. It's a feed you push yourself through the API rather than an account a user logs into, so it's out of scope for this page.

## Bank and card connections

A `card` connection links a user's bank account or credit or debit card, the same kind of linking Plaid provides. Once connected, Sail reports one expense per transaction. See [Transaction-Level and Item-Level Expenses](/docs/concepts/transaction-level-and-item-level-expenses) for how that transaction-level data is structured.

## Merchant connections

A `store` connection has a user log into a merchant directly (Amazon, Walgreens, Target, CVS, Walmart, and Costco, among others) through Sail's [Connect Account Widget](/docs/concepts/connect-widget). Instead of one expense per transaction, Sail reports individual products, giving you item-level detail a card connection alone can't. See [Transaction-Level and Item-Level Expenses](/docs/concepts/transaction-level-and-item-level-expenses) for how transaction- and item-level data relate.

## HSA/FSA connections

A `benefit_account` connection links a user's HSA, FSA, or HRA administrator, for example Health Equity. Unlike a card or store connection, it doesn't produce expenses, it produces account information:

* Balance
* Contribution activity
* Owner identity
* Deposit numbers

One administrator login can hold more than one account. A single Health Equity login, for example, can expose both an HSA and an LPFSA, each with its own `account_id`. Sail also publishes a directory of supported administrators through [List HSA/FSA Administrators](/reference/administrators/get-administrators), listing each one's capabilities and login URLs.

### Where account information lives

Account information isn't one object, it's assembled from six separate endpoints, each gated by its own scope and product requirement.

* [Get Account](/reference/accounts/get-users-user-id-accounts-account-id) returns balance and account type. Requires `benefit_account` scope and product.
* [List Activity](/reference/accounts/get-users-user-id-accounts-account-id-activity) returns contribution, distribution, interest, and fee history. Requires `benefit_account` scope and product.
* [Get Contribution Summary](/reference/accounts/get-users-user-id-accounts-account-id-contributions-summary) returns year-to-date contributions against the IRS limit. Requires `benefit_account` scope and product.
* [Get Account & Routing Numbers](/reference/accounts/get-users-user-id-accounts-account-id-numbers) returns masked deposit numbers. Requires `account_numbers` scope, product, and a user token.
* [Reveal Full Account Number](/reference/accounts/post-users-user-id-accounts-account-id-numbers-reveal) returns the full, unmasked deposit numbers. Requires `account_numbers` scope, product, and a user token with `numbers:reveal`.
* [Get Account Owner Identity](/reference/identity/get-users-user-id-accounts-account-id-identity) returns the account owner's name, address, email, and phone. Requires `identity` scope, product, and a user token.

{/* PENDING: this table reflects everything currently in api/api-spec.yaml's Account, AccountNumbers, and Identity schemas, but the complete, canonical field list hasn't been confirmed by Sail. See [[04-hsa-account-info-field-list]], still open. Don't present this as exhaustive until that's resolved. */}

### Deposit numbers are masked by default

`GET .../accounts/{account_id}/numbers` returns the account number masked (for example, `••••3388`) alongside the routing number, which is returned unmasked since routing numbers are public per institution. This is safe to display and to poll.

The full, unmasked account number requires a separate call, `POST .../accounts/{account_id}/numbers/reveal`. Every reveal is audit-logged and rate-limited per user. Treat the response as a one-time read for immediate use, such as initiating a deposit, and don't store it unencrypted. See [Scoped API Keys](/docs/concepts/scoped-api-keys) for why revealing a full account number needs a key with `account_numbers` scope plus an ephemeral user token, on top of the base connection.

### Owner identity is answered per account, not per user

`GET .../accounts/{account_id}/identity` returns the administrator-reported owner of that specific account, names, emails, phones, and addresses. This is deliberately scoped to the account, not aggregated across a user's connections, because the question "who owns the account I'm about to deposit into" must be answered from that account's own source. Since HSAs are individually owned, expect exactly one owner. This is a different endpoint from a user's originated identity (the contact details supplied when the user was created), which lives at `GET /users/{user_id}/identity` instead.

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

Once a user's expenses are eligible, eligible funds can be reimbursed from their HSA/FSA back to them. See [Reimbursement](/docs/concepts/reimbursement) for the preconditions, the status lifecycle, and how a reimbursement can fail.

</Callout>

## Next steps

* To connect a user's card or store accounts and start retrieving expenses, see [Enrich Transactions with Item-Level Data](/docs/guides/enrich-transactions-with-item-level-data).
* To connect a user's HSA/FSA administrator and read their account information back, see [Connect HSA/FSA Accounts](/docs/guides/connect-hsa-fsa-accounts).
* To see how Sail signals when new account data is ready, see [Receiving New Data](/docs/concepts/receiving-new-data).