Confidence envelope
ZIP-mode and SST lookups return a top-level confidence field with
one of four coarse buckets:
| Level | What it means | What to do |
|---|---|---|
exact | Exact boundary match — a ZIP+4 boundary row, or an address the state’s locator placed in a single jurisdiction | Trust the rate |
high | Address resolved by state DoR locator | Trust the rate |
medium | ZIP-centroid resolution; rate is the most common for that ZIP | Surface the rate; consider re-querying in address mode for high-value transactions |
low | Best-guess answer (rare; usually means coverage gap) | Don’t auto-bill — surface to a human |
The confidence is independent of the response’s row_count — a
“medium”-confidence response can have one row (the ZIP didn’t
straddle anything) or multiple (it did). Check both.
For the 23 Streamlined Sales Tax (SST) states, the top-level
confidence reflects how precisely the address resolved:
Resolution (matched_via) | confidence |
|---|---|
zip4 (exact ZIP+4 boundary row) | exact |
tiger_place / city_name (place resolved) | high |
zip5 (ZIP-level) | medium |
state_only, local-bearing state (a local may have been missed) | low |
state_only, flat no-local state (IN, KY, MI, NJ, RI) | high |
A state_only / low answer means we could not place the address in a
local jurisdiction and served the bare state rate — don’t auto-bill it;
surface to a human or re-query.
The five states with no local sales tax at all (Indiana, Kentucky,
Michigan, New Jersey, Rhode Island) are the exception: there, state_only
is the complete and only possible answer, so it reads high (fully
trustworthy), not low. This is derived from the rate data (does the state
have any local jurisdiction?), not a hard-coded list. It is high rather
than exact because exact is a ZIP+4/address-level geographic-precision claim —
here the geography simply doesn’t affect the rate.
SST responses also carry a richer
per-row rows[].confidence block (level, special_basis,
special_districts) describing special-district certainty; the top-level
scalar above is the coarse overall signal.
Texas address-mode lookups carry a confidence — typically high,
dropping to medium / low when the match is less certain.