Response shape & modes

GET /v1/tax/{state} returns one of two response shapes, selected by the mode query parameter. Every response echoes the shape it served in the X-TaxQL-Mode header (simple or full).

Default: `mode=simple`

A flat, single-rate object plus a diagnostic meta block. This is what most integrations want — one answer, uniform across every state.

{
  "rate": {
    "zip": "77002",
    "state": "TX",
    "state_rate": "0.06250",
    "county": "HARRIS",
    "county_rate": "0.00000",
    "city": "HOUSTON",
    "city_rate": "0.00000",
    "combined_district_rate": "0.02000",
    "combined_rate": "0.08250",
    "freight_taxable": true
  },
  "meta": {
    "resolved_via": "comptroller_locator",
    "confidence": "high",
    "period": "20262",
    "warnings": []
  }
}

For an ambiguous ZIP, simple mode resolves to the single highest-weight jurisdiction and records the ambiguity in meta.confidence / meta.warnings. Use mode=full when you need every candidate.

Verbose: `mode=full`

The full per-jurisdiction body — rows[] with each jurisdiction’s components, resolved_place, the ambiguous_zip5 envelope, billing, and warnings. Unchanged from the previous default except that rate fields are now strings (see below).

GET /v1/tax/tx?zip=77002&mode=full

?mode=simple is accepted explicitly and is identical to the default. Any other value returns 400 with the list of valid modes.

Rate values are strings

Every rate-bearing field renders as a fixed 5-decimal string ("0.06250", "0.00000") in both shapes. This avoids floating-point artifacts (e.g. 0.010000000000000002) leaking into JSON and gives you byte-stable values. Parse with your language’s decimal/float parser:

rate = float(response["rate"]["combined_rate"])   # 0.0825

Non-rate numerics (ambiguity weights, allocation percentages) remain JSON numbers.

Migrating

If your integration…	Do this
reads only the total rate / a flat rate object	Nothing — the new default is simpler. Parse the string rate fields with `float()`.
reads `rows[]`, `resolved_place`, or the component breakdown	Add `?mode=full` to your requests to keep the verbose shape.
pins exact float rate values	Parse the 5-decimal strings (`float(...)`) in both modes.

Check the X-TaxQL-Mode response header to confirm which shape you received.