Health & education accounts API
HSAs and Coverdell ESAs carry their own contribution-limit tables (as data, per year), qualified-expense distribution kinds, and the same fail-closed tax records. The API surface is identical in shape to the retirement family — open, fund, invest, distribute — with account-type rules resolved from reference data at every gate.
| Family | api-accounts-hsa-esa |
|---|---|
| Scope | Accounts |
| Authorization | Grant-based, deny by default — see authentication |
| Full catalog | API reference, with the OpenAPI document generated from the code |
What this family enforces
HSAs and Coverdell ESAs carry their own contribution-limit tables (as data, per year), qualified-expense distribution kinds, and the same fail-closed tax records. The API surface is identical in shape to the retirement family — open, fund, invest, distribute — with account-type rules resolved from reference data at every gate.
These are constraints the platform applies, not options a caller can switch off. Availability still depends on the operating institution’s authority and configuration — resolve it at runtime with GET https://api.a8core.io/v1/account-types rather than hard-coding it.
Platform laws
Every operation in this family obeys the same five rules as the rest of the platform.
| Law | What it means here |
|---|---|
| Grant-based, deny by default | Every operation is authorized against an explicit grant. Absence of a grant is a denial, not a fallback. |
| Idempotency keys on writes | Every write carries an idempotency key, so a retried request settles once rather than twice. |
| The Create/Update naming standard | Operations are named for what they do to the record, and each Create has the Update that pairs with it. |
| Decision records with policy identifiers | Each decision is written down with the policy that produced it, so an outcome can be explained later. |
| Statements that tie out before they publish | A statement is not published until it reconciles. A statement that does not tie out does not go out. |
Operations
The operations below are the documented entry points for this family. The API reference carries the full contract for each, and the OpenAPI document is generated from the code rather than written by hand.
Writes are idempotent: send an idempotency key and a retry settles once. State changes emit events — see webhooks and webhook keys.