What Is the Classify Expense API?

The Classify Expense API tells you which of your end users' purchases qualify as eligible healthcare expenses. It classifies a transaction or a product, depending on the data it starts from, and returns an eligibility outcome for each one, checked against Section 213(d) of the US tax code and IRS Publication 502. These are the same rules HSA, FSA, and HRA administrators use.

What the API classifies

Sail classifies an expense the same way whether it starts as a transaction or as a product. What differs is where the expense comes from and how much detail Sail has about it.

How Sail classifies a transaction

A transaction is the flat record you already have, such as a single charge at a pharmacy. You push it to an external connection, and Sail returns one outcome for the whole charge. When the transaction alone doesn't say what was bought, the outcome can be itemization_required.

How Sail classifies a product

A product is one item inside a purchase. When an end user connects a store account, the Itemize Transaction API returns one expense per product, and Sail classifies each product on its own, so a single purchase can hold products with different outcomes. See Classifying Item-Level Expenses for how product outcomes differ from transaction outcomes.

What a classified expense contains

Each transaction you send, and each product a store connection returns, becomes an Expense. Along with the amount, date, and merchant, each expense carries:

section_213d_classification.status, the eligibility outcome: eligible, ineligible, itemization_required, lmn_required, or processing while Sail is still working on it.
section_213d_classification.category and reasoning, which say what kind of medical expense it is and why Sail reached that outcome.
enrichment, holding a spend category, subcategory, and merchant category code where available.
merchant.supported_merchant_id, set when Sail can connect to that store for item-level detail.

See Expense Classification for what each outcome means.

How classifying a transaction works

Classifying a transaction you push takes three steps:

Your backend creates an external connection and pushes a batch of transactions to it, up to 500 per request.
Sail classifies each transaction automatically. There's no separate "classify this" call, since classification is part of processing every expense.
Sail sends a webhook when the batch is done, and your backend reads the outcomes from the API.

The Classify Your Transactions quickstart walks through all three steps.

Why classification matters

Deciding what counts as a medical expense is hard to do by hand. The IRS publishes no complete list of eligible products, and many purchases are mixed. A single pharmacy charge can hold a prescription and a birthday card, and some items, like a humidifier, are eligible only with a Letter of Medical Necessity (LMN).

Sail gives you a decision for each expense, plus the reason, so your application doesn't need its own eligibility rules. When the transaction alone isn't enough, the outcome tells you what's missing. itemization_required means Sail needs the items in the basket, which an itemized receipt or a store connection supplies.

Who it's for

The Classify Expense API fits an application that needs an eligibility answer for what its end users buy. You can start from transactions, from products, or both. Choose it if:

You already pull your end users' transactions from a bank feed or your own ledger, and you want an answer with no step your end users ever see.
You want a separate answer for each product in a purchase, and your end users can connect a store account.
You build a benefits, personal finance, or tax planning product.

Classifying a transaction doesn't need a store account or an HSA/FSA account. You can add item-level detail later with the Itemize Transaction API, which turns itemization_required into a per-product answer.

Next steps

To push your first batch and read the outcomes, see the Classify Your Transactions quickstart.
To see how each product gets its own outcome, see Classifying Item-Level Expenses.
To see what each outcome means and how to resolve the ones that need more, see Expense Classification.
To supply the items behind a mixed-basket expense, see Upload a Receipt.