{ "components": { "schemas": { "Component": { "additionalProperties": false, "properties": { "message": { "description": "Optional status message", "type": "string" }, "status": { "description": "Component status", "enum": [ "healthy", "degraded", "unhealthy" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "ErrorDetail": { "additionalProperties": false, "properties": { "location": { "description": "Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'", "type": "string" }, "message": { "description": "Error message text", "type": "string" }, "value": { "description": "The value at the given location" } }, "type": "object" }, "ErrorModel": { "additionalProperties": false, "properties": { "detail": { "description": "A human-readable explanation specific to this occurrence of the problem.", "examples": [ "Property foo is required but is missing." ], "type": "string" }, "errors": { "description": "Optional list of individual error details", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "type": [ "array", "null" ] }, "instance": { "description": "A URI reference that identifies the specific occurrence of the problem.", "examples": [ "https://example.com/error-log/abc123" ], "format": "uri", "type": "string" }, "status": { "description": "HTTP status code", "examples": [ 400 ], "format": "int64", "type": "integer" }, "title": { "description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.", "examples": [ "Bad Request" ], "type": "string" }, "type": { "default": "about:blank", "description": "A URI reference to human-readable documentation for the error.", "examples": [ "https://example.com/errors/example" ], "format": "uri", "type": "string" } }, "type": "object" }, "HealthResponse": { "additionalProperties": false, "properties": { "components": { "additionalProperties": { "$ref": "#/components/schemas/Component" }, "description": "Component health statuses", "type": "object" }, "status": { "description": "Overall system status", "enum": [ "healthy", "degraded", "unhealthy" ], "type": "string" }, "timestamp": { "description": "Health check timestamp", "format": "date-time", "type": "string" }, "version": { "description": "API version", "type": "string" } }, "required": [ "status", "version", "timestamp", "components" ], "type": "object" }, "MetadataResponse": { "additionalProperties": false, "properties": { "buildTime": { "description": "Build timestamp", "type": "string" }, "environment": { "description": "Environment name", "type": "string" }, "features": { "additionalProperties": { "type": "boolean" }, "description": "Enabled features", "type": "object" }, "gitCommit": { "description": "Git commit hash", "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Additional metadata", "type": "object" }, "version": { "description": "API version", "type": "string" } }, "required": [ "version", "environment", "buildTime", "gitCommit", "features", "metadata" ], "type": "object" }, "MetricsResponse": { "additionalProperties": false, "properties": { "core_request_count": { "description": "Core request count", "format": "int64", "type": "integer" }, "core_request_limit": { "description": "Core request limit", "format": "int64", "type": "integer" }, "core_usage_percent": { "description": "Core usage percentage", "format": "double", "type": "number" }, "geo_enabled": { "description": "Geo features enabled", "type": "boolean" }, "geo_request_count": { "description": "Geo request count", "format": "int64", "type": "integer" }, "geo_request_limit": { "description": "Geo request limit", "format": "int64", "type": "integer" }, "geo_usage_percent": { "description": "Geo usage percentage", "format": "double", "type": "number" }, "is_active": { "description": "Account active status", "type": "boolean" }, "last_updated": { "description": "Last update timestamp", "format": "date-time", "type": "string" } }, "required": [ "core_request_count", "core_request_limit", "core_usage_percent", "geo_enabled", "geo_request_count", "geo_request_limit", "geo_usage_percent", "is_active", "last_updated" ], "type": "object" }, "TICData": { "additionalProperties": false, "properties": { "category": { "description": "TIC category", "type": "string" }, "code": { "description": "TIC code", "type": "string" }, "description": { "description": "TIC description", "type": "string" }, "taxable": { "description": "Taxability status", "type": "boolean" } }, "required": [ "code", "description", "category", "taxable" ], "type": "object" }, "TICResponse": { "additionalProperties": false, "properties": { "count": { "description": "Total number of TIC codes", "format": "int64", "type": "integer" }, "items": { "description": "List of TIC codes", "items": { "$ref": "#/components/schemas/TICData" }, "type": [ "array", "null" ] } }, "required": [ "items", "count" ], "type": "object" }, "V10Response": { "additionalProperties": false, "properties": { "rCode": { "description": "Response code (100=success)", "examples": [ 100 ], "format": "int64", "type": "integer" }, "results": { "description": "Tax rate results", "items": { "$ref": "#/components/schemas/V10TaxResult" }, "type": [ "array", "null" ] }, "version": { "description": "API version", "type": "string" } }, "required": [ "version", "rCode", "results" ], "type": "object" }, "V10TaxResult": { "additionalProperties": false, "properties": { "geoCity": { "description": "Geocoded city name", "type": "string" }, "geoCounty": { "description": "Geocoded county name", "type": "string" }, "geoPostalCode": { "description": "Geocoded postal code", "type": "string" }, "geoState": { "description": "Geocoded state", "type": "string" }, "taxSales": { "description": "Total sales tax rate", "format": "float", "type": "number" }, "taxUse": { "description": "Total use tax rate", "format": "float", "type": "number" }, "txbFreight": { "description": "Freight taxability", "type": "string" }, "txbService": { "description": "Service taxability", "type": "string" } }, "required": [ "geoPostalCode", "geoCity", "geoCounty", "geoState", "taxSales", "taxUse", "txbService", "txbFreight" ], "type": "object" }, "V20Response": { "additionalProperties": false, "properties": { "rCode": { "description": "Response code (100=success)", "format": "int64", "type": "integer" }, "results": { "description": "Tax rate results", "items": { "$ref": "#/components/schemas/V20TaxResult" }, "type": [ "array", "null" ] }, "version": { "description": "API version", "type": "string" } }, "required": [ "version", "rCode", "results" ], "type": "object" }, "V20TaxResult": { "additionalProperties": false, "properties": { "citySalesTax": { "description": "City sales tax rate", "format": "float", "type": "number" }, "cityTaxCode": { "description": "City tax code", "type": "string" }, "cityUseTax": { "description": "City use tax rate", "format": "float", "type": "number" }, "countySalesTax": { "description": "County sales tax rate", "format": "float", "type": "number" }, "countyTaxCode": { "description": "County tax code", "type": "string" }, "countyUseTax": { "description": "County use tax rate", "format": "float", "type": "number" }, "geoCity": { "description": "Geocoded city name", "type": "string" }, "geoCounty": { "description": "Geocoded county name", "type": "string" }, "geoPostalCode": { "description": "Geocoded postal code", "type": "string" }, "geoState": { "description": "Geocoded state", "type": "string" }, "stateSalesTax": { "description": "State sales tax rate", "format": "float", "type": "number" }, "stateUseTax": { "description": "State use tax rate", "format": "float", "type": "number" }, "taxSales": { "description": "Total sales tax rate", "format": "float", "type": "number" }, "taxUse": { "description": "Total use tax rate", "format": "float", "type": "number" }, "txbFreight": { "description": "Freight taxability", "type": "string" }, "txbService": { "description": "Service taxability", "type": "string" } }, "required": [ "stateSalesTax", "stateUseTax", "citySalesTax", "cityUseTax", "cityTaxCode", "countySalesTax", "countyUseTax", "countyTaxCode", "geoPostalCode", "geoCity", "geoCounty", "geoState", "taxSales", "taxUse", "txbService", "txbFreight" ], "type": "object" }, "V40Response": { "additionalProperties": false, "properties": { "rCode": { "description": "Response code (100=success)", "format": "int64", "type": "integer" }, "results": { "description": "Tax rate results", "items": { "$ref": "#/components/schemas/V40TaxResult" }, "type": [ "array", "null" ] }, "version": { "description": "API version", "type": "string" } }, "required": [ "version", "rCode", "results" ], "type": "object" }, "V40TaxResult": { "additionalProperties": false, "properties": { "citySalesTax": { "description": "City sales tax rate", "format": "float", "type": "number" }, "cityTaxCode": { "description": "City tax code", "type": "string" }, "cityUseTax": { "description": "City use tax rate", "format": "float", "type": "number" }, "countySalesTax": { "description": "County sales tax rate", "format": "float", "type": "number" }, "countyTaxCode": { "description": "County tax code", "type": "string" }, "countyUseTax": { "description": "County use tax rate", "format": "float", "type": "number" }, "district1Code": { "description": "District 1 code", "type": "string" }, "district1SalesTax": { "description": "District 1 sales tax", "format": "float", "type": "number" }, "district1UseTax": { "description": "District 1 use tax", "format": "float", "type": "number" }, "districtSalesTax": { "description": "Total district sales tax", "format": "float", "type": "number" }, "districtUseTax": { "description": "Total district use tax", "format": "float", "type": "number" }, "geoCity": { "description": "Geocoded city name", "type": "string" }, "geoCounty": { "description": "Geocoded county name", "type": "string" }, "geoPostalCode": { "description": "Geocoded postal code", "type": "string" }, "geoState": { "description": "Geocoded state", "type": "string" }, "stateSalesTax": { "description": "State sales tax rate", "format": "float", "type": "number" }, "stateUseTax": { "description": "State use tax rate", "format": "float", "type": "number" }, "taxSales": { "description": "Total sales tax rate", "format": "float", "type": "number" }, "taxUse": { "description": "Total use tax rate", "format": "float", "type": "number" }, "txbFreight": { "description": "Freight taxability", "type": "string" }, "txbService": { "description": "Service taxability", "type": "string" } }, "required": [ "districtSalesTax", "districtUseTax", "district1Code", "district1SalesTax", "district1UseTax", "stateSalesTax", "stateUseTax", "citySalesTax", "cityUseTax", "cityTaxCode", "countySalesTax", "countyUseTax", "countyTaxCode", "geoPostalCode", "geoCity", "geoCounty", "geoState", "taxSales", "taxUse", "txbService", "txbFreight" ], "type": "object" }, "V50AddressDetail": { "additionalProperties": false, "properties": { "geoLat": { "description": "Geocoded latitude", "format": "double", "type": "number" }, "geoLng": { "description": "Geocoded longitude", "format": "double", "type": "number" }, "incorporated": { "description": "Incorporation status", "type": "string" }, "normalizedAddress": { "description": "Normalized address", "type": "string" } }, "required": [ "normalizedAddress", "incorporated", "geoLat", "geoLng" ], "type": "object" }, "V50Response": { "additionalProperties": false, "properties": { "addressDetail": { "$ref": "#/components/schemas/V50AddressDetail", "description": "Address details" }, "rCode": { "description": "Response code (100=success)", "format": "int64", "type": "integer" }, "results": { "description": "Tax rate results", "items": { "$ref": "#/components/schemas/V50TaxResult" }, "type": [ "array", "null" ] }, "satTaxDetail": { "$ref": "#/components/schemas/V50SingleArticleTax", "description": "Tennessee Single Article Tax details" }, "version": { "description": "API version", "type": "string" } }, "required": [ "version", "rCode", "results", "addressDetail" ], "type": "object" }, "V50SingleArticleTax": { "additionalProperties": false, "properties": { "appliedTotal": { "description": "Applied total amount", "type": "string" }, "countyTaxRate": { "description": "County tax rate", "type": "string" }, "localTaxLimit": { "description": "Local tax limit", "type": "string" }, "localTaxTotal": { "description": "Local tax total", "type": "string" }, "stateAdditionalTaxTotal": { "description": "State additional tax total", "type": "string" } }, "required": [ "appliedTotal", "countyTaxRate", "localTaxLimit", "localTaxTotal", "stateAdditionalTaxTotal" ], "type": "object" }, "V50TaxResult": { "additionalProperties": false, "properties": { "citySalesTax": { "description": "City sales tax rate", "format": "float", "type": "number" }, "cityTaxCode": { "description": "City tax code", "type": "string" }, "cityUseTax": { "description": "City use tax rate", "format": "float", "type": "number" }, "countySalesTax": { "description": "County sales tax rate", "format": "float", "type": "number" }, "countyTaxCode": { "description": "County tax code", "type": "string" }, "countyUseTax": { "description": "County use tax rate", "format": "float", "type": "number" }, "district1Code": { "description": "District 1 code", "type": "string" }, "district1SalesTax": { "description": "District 1 sales tax", "format": "float", "type": "number" }, "district1UseTax": { "description": "District 1 use tax", "format": "float", "type": "number" }, "district2Code": { "description": "District 2 code", "type": "string" }, "district2SalesTax": { "description": "District 2 sales tax", "format": "double", "type": "number" }, "district2UseTax": { "description": "District 2 use tax", "format": "double", "type": "number" }, "district3Code": { "description": "District 3 code", "type": "string" }, "district3SalesTax": { "description": "District 3 sales tax", "format": "double", "type": "number" }, "district3UseTax": { "description": "District 3 use tax", "format": "double", "type": "number" }, "district4Code": { "description": "District 4 code", "type": "string" }, "district4SalesTax": { "description": "District 4 sales tax", "format": "double", "type": "number" }, "district4UseTax": { "description": "District 4 use tax", "format": "double", "type": "number" }, "district5Code": { "description": "District 5 code", "type": "string" }, "district5SalesTax": { "description": "District 5 sales tax", "format": "double", "type": "number" }, "district5UseTax": { "description": "District 5 use tax", "format": "double", "type": "number" }, "districtSalesTax": { "description": "Total district sales tax", "format": "float", "type": "number" }, "districtUseTax": { "description": "Total district use tax", "format": "float", "type": "number" }, "geoCity": { "description": "Geocoded city name", "type": "string" }, "geoCounty": { "description": "Geocoded county name", "type": "string" }, "geoPostalCode": { "description": "Geocoded postal code", "type": "string" }, "geoState": { "description": "Geocoded state", "type": "string" }, "originDestination": { "description": "Origin or destination based", "type": "string" }, "stateSalesTax": { "description": "State sales tax rate", "format": "float", "type": "number" }, "stateUseTax": { "description": "State use tax rate", "format": "float", "type": "number" }, "taxSales": { "description": "Total sales tax rate", "format": "float", "type": "number" }, "taxUse": { "description": "Total use tax rate", "format": "float", "type": "number" }, "txbFreight": { "description": "Freight taxability", "type": "string" }, "txbService": { "description": "Service taxability", "type": "string" } }, "required": [ "district2Code", "district2SalesTax", "district2UseTax", "district3Code", "district3SalesTax", "district3UseTax", "district4Code", "district4SalesTax", "district4UseTax", "district5Code", "district5SalesTax", "district5UseTax", "originDestination", "districtSalesTax", "districtUseTax", "district1Code", "district1SalesTax", "district1UseTax", "stateSalesTax", "stateUseTax", "citySalesTax", "cityUseTax", "cityTaxCode", "countySalesTax", "countyUseTax", "countyTaxCode", "geoPostalCode", "geoCity", "geoCounty", "geoState", "taxSales", "taxUse", "txbService", "txbFreight" ], "type": "object" }, "V60AddressDetail": { "additionalProperties": false, "properties": { "geoLat": { "description": "Geocoded latitude", "format": "float", "type": "number" }, "geoLng": { "description": "Geocoded longitude", "format": "float", "type": "number" }, "incorporated": { "description": "Incorporation status", "enum": [ "true", "false" ], "type": "string" }, "normalizedAddress": { "description": "Normalized address", "type": "string" } }, "required": [ "normalizedAddress", "incorporated", "geoLat", "geoLng" ], "type": "object" }, "V60BaseRate": { "additionalProperties": false, "properties": { "jur_description": { "description": "Jurisdiction description", "type": "string" }, "jur_name": { "description": "Jurisdiction name", "enum": [ "US_STATE", "US_COUNTY", "US_CITY", "US_DISTRICT" ], "type": "string" }, "jur_tax_code": { "description": "Tax code for jurisdiction", "type": "string" }, "jur_type": { "description": "Jurisdiction type", "enum": [ "US_STATE_SALES_TAX", "US_STATE_USE_TAX", "US_COUNTY_SALES_TAX", "US_COUNTY_USE_TAX", "US_CITY_SALES_TAX", "US_CITY_USE_TAX", "US_DISTRICT_SALES_TAX", "US_DISTRICT_USE_TAX" ], "type": "string" }, "rate": { "description": "Tax rate", "format": "float", "type": "number" }, "rate_id": { "description": "Rate identifier from tax table", "type": "string" } }, "required": [ "rate", "rate_id", "jur_type", "jur_name", "jur_description", "jur_tax_code" ], "type": "object" }, "V60Metadata": { "additionalProperties": false, "properties": { "rCode": { "description": "Response code (100=success)", "examples": [ 100 ], "format": "int64", "type": "integer" }, "version": { "description": "API version", "examples": [ "v60" ], "type": "string" } }, "required": [ "version", "rCode" ], "type": "object" }, "V60OriginDestination": { "additionalProperties": false, "properties": { "adjustment_type": { "description": "Origin/destination type", "examples": [ "ORIGIN_DESTINATION" ], "type": "string" }, "description": { "description": "Origin/destination description", "type": "string" }, "value": { "description": "Origin/destination value", "enum": [ "O", "D" ], "type": "string" } }, "required": [ "adjustment_type", "description", "value" ], "type": "object" }, "V60Response": { "additionalProperties": false, "properties": { "addressDetail": { "$ref": "#/components/schemas/V60AddressDetail", "description": "Address details" }, "base_rates": { "description": "Base tax rates by jurisdiction", "items": { "$ref": "#/components/schemas/V60BaseRate" }, "type": [ "array", "null" ] }, "metadata": { "$ref": "#/components/schemas/V60Metadata", "description": "Response metadata" }, "origin_destination": { "$ref": "#/components/schemas/V60OriginDestination", "description": "Origin/destination taxation info" }, "service": { "$ref": "#/components/schemas/V60Service", "description": "Service taxability information" }, "shipping": { "$ref": "#/components/schemas/V60Shipping", "description": "Shipping taxability information" }, "tax_summaries": { "description": "Tax rate summaries", "items": { "$ref": "#/components/schemas/V60TaxSummary" }, "type": [ "array", "null" ] } }, "required": [ "metadata", "base_rates", "service", "shipping", "origin_destination", "tax_summaries", "addressDetail" ], "type": "object" }, "V60Service": { "additionalProperties": false, "properties": { "adjustment_type": { "description": "Service adjustment type", "examples": [ "SERVICE_TAXABLE" ], "type": "string" }, "description": { "description": "Service description", "type": "string" }, "taxable": { "description": "Taxability indicator", "enum": [ "Y", "N" ], "type": "string" } }, "required": [ "adjustment_type", "taxable", "description" ], "type": "object" }, "V60Shipping": { "additionalProperties": false, "properties": { "adjustment_type": { "description": "Shipping adjustment type", "examples": [ "FREIGHT_TAXABLE" ], "type": "string" }, "description": { "description": "Shipping description", "type": "string" }, "taxable": { "description": "Taxability indicator", "enum": [ "Y", "N" ], "type": "string" } }, "required": [ "adjustment_type", "taxable", "description" ], "type": "object" }, "V60TaxSummary": { "additionalProperties": false, "properties": { "rate": { "description": "Summary tax rate", "format": "float", "type": "number" }, "summary_name": { "description": "Summary description", "type": "string" }, "tax_type": { "description": "Tax type", "enum": [ "SALES_TAX", "USE_TAX" ], "type": "string" } }, "required": [ "rate", "tax_type", "summary_name" ], "type": "object" } }, "securitySchemes": { "ApiKeyHeader": { "description": "API key in header", "in": "header", "name": "X-API-KEY", "type": "apiKey" }, "ApiKeyQuery": { "description": "API key for authentication", "in": "query", "name": "key", "type": "apiKey" } } }, "info": { "contact": { "email": "support@ziptax.com", "name": "ZipTax Support", "url": "https://ziptax.com" }, "description": "Production-ready RESTful service for US and Canadian sales tax data lookup", "title": "ZipTax API", "version": "5.0.0" }, "openapi": "3.1.0", "paths": { "/account/metrics": { "get": { "description": "Returns usage metrics for the authenticated account", "operationId": "getAccountMetrics", "parameters": [ { "description": "API key for authentication", "explode": false, "in": "query", "name": "key", "schema": { "description": "API key for authentication", "maxLength": 100, "minLength": 10, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "ApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "summary": "Get Account Metrics", "tags": [ "Account" ] } }, "/data/tic": { "get": { "description": "Returns Taxability Information Code (TIC) data", "operationId": "getTICData", "parameters": [ { "description": "Response format", "explode": false, "in": "query", "name": "format", "schema": { "default": "json", "description": "Response format", "enum": [ "json", "xml" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TICResponse" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Get TIC Codes", "tags": [ "Data" ] } }, "/request/v10": { "get": { "description": "Returns basic tax rate information with 8 fields including combined rates", "operationId": "getTaxRatesV10", "parameters": [ { "description": "API key for authentication", "example": "your-api-key", "explode": false, "in": "query", "name": "key", "schema": { "description": "API key for authentication", "examples": [ "your-api-key" ], "maxLength": 100, "minLength": 10, "type": "string" } }, { "description": "Response format", "explode": false, "in": "query", "name": "format", "schema": { "default": "json", "description": "Response format", "enum": [ "json", "xml" ], "type": "string" } }, { "description": "5-digit postal code", "example": "90210", "explode": false, "in": "query", "name": "postalcode", "schema": { "description": "5-digit postal code", "examples": [ "90210" ], "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}$", "type": "string" } }, { "description": "Street address for geocoding", "example": "123 Main St", "explode": false, "in": "query", "name": "address", "schema": { "description": "Street address for geocoding", "examples": [ "123 Main St" ], "maxLength": 100, "type": "string" } }, { "description": "State abbreviation", "example": "CA", "explode": false, "in": "query", "name": "state", "schema": { "description": "State abbreviation", "examples": [ "CA" ], "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]{2}$", "type": "string" } }, { "description": "City name", "example": "Beverly Hills", "explode": false, "in": "query", "name": "city", "schema": { "description": "City name", "examples": [ "Beverly Hills" ], "maxLength": 50, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V10Response" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "ApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "summary": "Get Tax Rates (v1.0)", "tags": [ "Tax Rates" ] } }, "/request/v20": { "get": { "description": "Returns detailed tax breakdown with 16 fields including use tax rates", "operationId": "getTaxRatesV20", "parameters": [ { "description": "API key for authentication", "example": "your-api-key", "explode": false, "in": "query", "name": "key", "schema": { "description": "API key for authentication", "examples": [ "your-api-key" ], "maxLength": 100, "minLength": 10, "type": "string" } }, { "description": "Response format", "explode": false, "in": "query", "name": "format", "schema": { "default": "json", "description": "Response format", "enum": [ "json", "xml" ], "type": "string" } }, { "description": "5-digit postal code", "example": "90210", "explode": false, "in": "query", "name": "postalcode", "schema": { "description": "5-digit postal code", "examples": [ "90210" ], "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}$", "type": "string" } }, { "description": "Street address for geocoding", "example": "123 Main St", "explode": false, "in": "query", "name": "address", "schema": { "description": "Street address for geocoding", "examples": [ "123 Main St" ], "maxLength": 100, "type": "string" } }, { "description": "State abbreviation", "example": "CA", "explode": false, "in": "query", "name": "state", "schema": { "description": "State abbreviation", "examples": [ "CA" ], "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]{2}$", "type": "string" } }, { "description": "City name", "example": "Beverly Hills", "explode": false, "in": "query", "name": "city", "schema": { "description": "City name", "examples": [ "Beverly Hills" ], "maxLength": 50, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V20Response" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "ApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "summary": "Get Tax Rates (v2.0)", "tags": [ "Tax Rates" ] } }, "/request/v30": { "get": { "description": "Returns tax rates with same structure as v2.0 (compatibility version)", "operationId": "getTaxRatesV30", "parameters": [ { "description": "API key for authentication", "example": "your-api-key", "explode": false, "in": "query", "name": "key", "schema": { "description": "API key for authentication", "examples": [ "your-api-key" ], "maxLength": 100, "minLength": 10, "type": "string" } }, { "description": "Response format", "explode": false, "in": "query", "name": "format", "schema": { "default": "json", "description": "Response format", "enum": [ "json", "xml" ], "type": "string" } }, { "description": "5-digit postal code", "example": "90210", "explode": false, "in": "query", "name": "postalcode", "schema": { "description": "5-digit postal code", "examples": [ "90210" ], "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}$", "type": "string" } }, { "description": "Street address for geocoding", "example": "123 Main St", "explode": false, "in": "query", "name": "address", "schema": { "description": "Street address for geocoding", "examples": [ "123 Main St" ], "maxLength": 100, "type": "string" } }, { "description": "State abbreviation", "example": "CA", "explode": false, "in": "query", "name": "state", "schema": { "description": "State abbreviation", "examples": [ "CA" ], "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]{2}$", "type": "string" } }, { "description": "City name", "example": "Beverly Hills", "explode": false, "in": "query", "name": "city", "schema": { "description": "City name", "examples": [ "Beverly Hills" ], "maxLength": 50, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V20Response" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "ApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "summary": "Get Tax Rates (v3.0)", "tags": [ "Tax Rates" ] } }, "/request/v40": { "get": { "description": "Returns tax rates with multi-district support (22+ fields)", "operationId": "getTaxRatesV40", "parameters": [ { "description": "API key for authentication", "example": "your-api-key", "explode": false, "in": "query", "name": "key", "schema": { "description": "API key for authentication", "examples": [ "your-api-key" ], "maxLength": 100, "minLength": 10, "type": "string" } }, { "description": "Response format", "explode": false, "in": "query", "name": "format", "schema": { "default": "json", "description": "Response format", "enum": [ "json", "xml" ], "type": "string" } }, { "description": "5-digit postal code", "example": "90210", "explode": false, "in": "query", "name": "postalcode", "schema": { "description": "5-digit postal code", "examples": [ "90210" ], "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}$", "type": "string" } }, { "description": "Street address for geocoding", "example": "123 Main St", "explode": false, "in": "query", "name": "address", "schema": { "description": "Street address for geocoding", "examples": [ "123 Main St" ], "maxLength": 100, "type": "string" } }, { "description": "State abbreviation", "example": "CA", "explode": false, "in": "query", "name": "state", "schema": { "description": "State abbreviation", "examples": [ "CA" ], "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]{2}$", "type": "string" } }, { "description": "City name", "example": "Beverly Hills", "explode": false, "in": "query", "name": "city", "schema": { "description": "City name", "examples": [ "Beverly Hills" ], "maxLength": 50, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V40Response" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "ApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "summary": "Get Tax Rates (v4.0)", "tags": [ "Tax Rates" ] } }, "/request/v40/activate": { "get": { "description": "Activates v4.0 features for the account", "operationId": "activateV40", "parameters": [ { "description": "API key for authentication", "explode": false, "in": "query", "name": "key", "schema": { "description": "API key for authentication", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": {}, "type": "object" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "security": [ { "ApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "summary": "Activate v4.0 Features", "tags": [ "Tax Rates" ] } }, "/request/v50": { "get": { "description": "Returns comprehensive tax rates with geocoding support, multi-district breakdown,\n\t\t\tand Tennessee Single Article Tax calculations. Supports both USA and Canada.", "operationId": "getTaxRatesV50", "parameters": [ { "description": "API key for authentication", "example": "your-api-key", "explode": false, "in": "query", "name": "key", "schema": { "description": "API key for authentication", "examples": [ "your-api-key" ], "maxLength": 100, "minLength": 10, "type": "string" } }, { "description": "Response format", "explode": false, "in": "query", "name": "format", "schema": { "default": "json", "description": "Response format", "enum": [ "json", "xml" ], "type": "string" } }, { "description": "Country code (USA/CAN)", "explode": false, "in": "query", "name": "countryCode", "schema": { "default": "USA", "description": "Country code (USA/CAN)", "enum": [ "USA", "CAN" ], "type": "string" } }, { "description": "5-digit postal code", "explode": false, "in": "query", "name": "postalcode", "schema": { "description": "5-digit postal code", "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}$", "type": "string" } }, { "description": "Street address for geocoding", "explode": false, "in": "query", "name": "address", "schema": { "description": "Street address for geocoding", "maxLength": 100, "type": "string" } }, { "description": "State name or abbreviation", "explode": false, "in": "query", "name": "state", "schema": { "description": "State name or abbreviation", "maxLength": 50, "type": "string" } }, { "description": "State code", "explode": false, "in": "query", "name": "stateCode", "schema": { "description": "State code", "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]{2}$", "type": "string" } }, { "description": "City name", "explode": false, "in": "query", "name": "city", "schema": { "description": "City name", "maxLength": 50, "type": "string" } }, { "description": "County name", "explode": false, "in": "query", "name": "county", "schema": { "description": "County name", "maxLength": 50, "type": "string" } }, { "description": "Latitude coordinate", "explode": false, "in": "query", "name": "lat", "schema": { "description": "Latitude coordinate", "format": "double", "maximum": 90, "minimum": -90, "type": "number" } }, { "description": "Longitude coordinate", "explode": false, "in": "query", "name": "lng", "schema": { "description": "Longitude coordinate", "format": "double", "maximum": 180, "minimum": -180, "type": "number" } }, { "description": "Address adjustment parameter", "explode": false, "in": "query", "name": "adjustment", "schema": { "description": "Address adjustment parameter", "maxLength": 100, "type": "string" } }, { "description": "Single Article Tax item total for Tennessee", "explode": false, "in": "query", "name": "sat_item_total", "schema": { "description": "Single Article Tax item total for Tennessee", "format": "double", "minimum": 0, "type": "number" } }, { "description": "Historical date for rates", "explode": false, "in": "query", "name": "historical", "schema": { "description": "Historical date for rates", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V50Response" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "ApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "summary": "Get Tax Rates (v5.0)", "tags": [ "Tax Rates" ] } }, "/request/v60": { "get": { "description": "Returns tax rates in a new structured format with separate base rates,\n\t\t\tservice/shipping taxability, and tax summaries. Built on v5.0 data but with enhanced organization.", "operationId": "getTaxRatesV60", "parameters": [ { "description": "API key for authentication", "example": "your-api-key", "explode": false, "in": "query", "name": "key", "schema": { "description": "API key for authentication", "examples": [ "your-api-key" ], "maxLength": 100, "minLength": 10, "type": "string" } }, { "description": "Response format", "explode": false, "in": "query", "name": "format", "schema": { "default": "json", "description": "Response format", "enum": [ "json", "xml" ], "type": "string" } }, { "description": "Country code (USA/CAN)", "explode": false, "in": "query", "name": "countryCode", "schema": { "default": "USA", "description": "Country code (USA/CAN)", "enum": [ "USA", "CAN" ], "type": "string" } }, { "description": "5-digit postal code", "explode": false, "in": "query", "name": "postalcode", "schema": { "description": "5-digit postal code", "maxLength": 5, "minLength": 5, "pattern": "^[0-9]{5}$", "type": "string" } }, { "description": "Street address for geocoding", "explode": false, "in": "query", "name": "address", "schema": { "description": "Street address for geocoding", "maxLength": 100, "type": "string" } }, { "description": "State name or abbreviation", "explode": false, "in": "query", "name": "state", "schema": { "description": "State name or abbreviation", "maxLength": 50, "type": "string" } }, { "description": "State code", "explode": false, "in": "query", "name": "stateCode", "schema": { "description": "State code", "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]{2}$", "type": "string" } }, { "description": "City name", "explode": false, "in": "query", "name": "city", "schema": { "description": "City name", "maxLength": 50, "type": "string" } }, { "description": "County name", "explode": false, "in": "query", "name": "county", "schema": { "description": "County name", "maxLength": 50, "type": "string" } }, { "description": "Latitude coordinate", "explode": false, "in": "query", "name": "lat", "schema": { "description": "Latitude coordinate", "format": "double", "maximum": 90, "minimum": -90, "type": "number" } }, { "description": "Longitude coordinate", "explode": false, "in": "query", "name": "lng", "schema": { "description": "Longitude coordinate", "format": "double", "maximum": 180, "minimum": -180, "type": "number" } }, { "description": "Address adjustment parameter", "explode": false, "in": "query", "name": "adjustment", "schema": { "description": "Address adjustment parameter", "maxLength": 100, "type": "string" } }, { "description": "Single Article Tax item total for Tennessee", "explode": false, "in": "query", "name": "sat_item_total", "schema": { "description": "Single Article Tax item total for Tennessee", "format": "double", "minimum": 0, "type": "number" } }, { "description": "Historical date for rates", "explode": false, "in": "query", "name": "historical", "schema": { "description": "Historical date for rates", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V60Response" } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Bad Request" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unauthorized" }, "422": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Unprocessable Entity" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Too Many Requests" }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Internal Server Error" } }, "security": [ { "ApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "summary": "Get Tax Rates (v6.0)", "tags": [ "Tax Rates" ] } }, "/system/health": { "get": { "description": "Returns the health status of the API and its components", "operationId": "getHealth", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Health Check", "tags": [ "System" ] } }, "/system/metadata": { "get": { "description": "Returns system metadata including version and environment information", "operationId": "getMetadata", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataResponse" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } }, "description": "Error" } }, "summary": "Get System Metadata", "tags": [ "System" ] } } }, "servers": [ { "description": "Production Server", "url": "https://api.ziptax.com" }, { "description": "Local Development Server", "url": "http://localhost:8080" } ], "tags": [ { "description": "Sales tax rate lookup operations", "name": "Tax Rates" }, { "description": "System health and metadata operations", "name": "System" }, { "description": "Account management and metrics", "name": "Account" }, { "description": "Tax data and TIC code operations", "name": "Data" } ] }