Documentation

Welcome to the SalesTaxAPI documentation. Get accurate, up-to-date sales tax rates for all 50 US states.

📚 What you'll find here:

  • • Complete API reference and parameters
  • • Authentication and security best practices
  • • Code examples in multiple languages
  • • Error handling and troubleshooting

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header using the Bearer scheme.

Authorization: Bearer YOUR_API_KEY

🔒 Keep your API key secure

Never expose your API key in client-side code or public repositories. Always make API calls from your backend server.

Quick Start

Get started in 3 simple steps:

Step 1: Get your API key

Sign up and generate your API key from the dashboard.

Step 2: Make your first request

Use the example below to fetch tax rates for any ZIP code.

Step 3: Integrate into your app

Use our code examples to integrate into your application.

cURL
curl -X GET "https://salestaxapi.io/api/rates?state=UT&zip=84043" \
  -H "Authorization: Bearer YOUR_API_KEY"

API Endpoints

GET/api/rates

Retrieve sales tax rate information for a specific location by state code and ZIP code.

Query Parameters

ParameterTypeRequiredDescription
statestringYesTwo-letter state code (e.g., "UT", "CA")
zipstringYes5-digit ZIP code

Response Format

All responses are returned in JSON format. Successful responses include a success field set to true.

Success Response (200 OK)

{
  "success": true,
  "data": {
    "zip": "84043",
    "state": "UT",
    "county": "Utah County",
    "city": "Lehi",
    "district": null,
    "total_rate": 0.0685,
    "breakdown": {
      "state_rate": 0.0485,
      "county_rate": 0.001,
      "city_rate": 0.01,
      "district_rate": 0.009
    },
    "multiple_jurisdictions": false,
    "confidence": "high",
    "last_updated": "2025-12-01T10:30:00Z",
    "source_url": "https://tax.utah.gov/...",
    "source_last_fetched": "2025-12-01T02:00:00Z"
  }
}

Response Fields

FieldTypeDescription
total_ratedecimalCombined tax rate (0.0685 = 6.85%)
state_ratedecimalState-level tax rate
county_ratedecimalCounty-level tax rate
city_ratedecimalCity-level tax rate
district_ratedecimalSpecial district tax rate
confidencestring"high", "medium", or "low" confidence level
last_updateddatetimeISO 8601 timestamp of last data update

Error Codes

Error responses include a success: false field and an error object with details.

400

INVALID_PARAMETERS

The state code or ZIP code format is invalid.

401

INVALID_API_KEY

The API key is missing, invalid, or inactive.

404

NOT_FOUND

No tax rate data found for the specified location.

429

RATE_LIMIT_EXCEEDED

You've exceeded the rate limit. Please retry after the specified time.

429

QUOTA_EXCEEDED

You've exceeded your monthly quota. Upgrade your plan or wait until next month.

500

INTERNAL_ERROR

An unexpected error occurred on our end. Please contact support if this persists.

Code Examples

JavaScript (Node.js)

const fetch = require('node-fetch');

async function getTaxRate(state, zip) {
  const response = await fetch(
    `https://salestaxapi.io/api/rates?state=${state}&zip=${zip}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  
  const data = await response.json();
  
  if (data.success) {
    console.log(`Tax rate for ${zip}: ${data.data.total_rate * 100}%`);
    return data.data;
  } else {
    console.error('Error:', data.error.message);
    throw new Error(data.error.code);
  }
}

// Usage
getTaxRate('UT', '84043')
  .then(rate => console.log(rate))
  .catch(err => console.error(err));

Python

import requests

def get_tax_rate(state, zip_code):
    url = f"https://salestaxapi.io/api/rates?state={state}&zip={zip_code}"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY"
    }
    
    response = requests.get(url, headers=headers)
    data = response.json()
    
    if data.get("success"):
        rate = data["data"]["total_rate"]
        print(f"Tax rate for {zip_code}: {rate * 100}%")
        return data["data"]
    else:
        error = data.get("error", {})
        print(f"Error: {error.get('message')}")
        raise Exception(error.get("code"))

# Usage
try:
    rate_data = get_tax_rate("UT", "84043")
    print(rate_data)
except Exception as e:
    print(f"Failed to fetch rate: {e}")

PHP

<?php

function getTaxRate($state, $zip) {
    $url = "https://salestaxapi.io/api/rates?state=" . $state . "&zip=" . $zip;
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer YOUR_API_KEY'
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    $data = json_decode($response, true);
    
    if ($data['success']) {
        $rate = $data['data']['total_rate'] * 100;
        echo "Tax rate for $zip: {$rate}%\n";
        return $data['data'];
    } else {
        echo "Error: " . $data['error']['message'] . "\n";
        throw new Exception($data['error']['code']);
    }
}

// Usage
try {
    $rateData = getTaxRate('UT', '84043');
    print_r($rateData);
} catch (Exception $e) {
    echo "Failed to fetch rate: " . $e->getMessage();
}

?>

cURL

# Basic request
curl -X GET "https://salestaxapi.io/api/rates?state=UT&zip=84043" \
  -H "Authorization: Bearer YOUR_API_KEY"

# With pretty-printed JSON output
curl -X GET "https://salestaxapi.io/api/rates?state=UT&zip=84043" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  | json_pp

# Save response to file
curl -X GET "https://salestaxapi.io/api/rates?state=UT&zip=84043" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o response.json

Rate Limits

To ensure fair usage and system stability, we enforce the following rate limits:

Per API Key

10

requests per second

Per IP Address

100

requests per hour

💡 Rate Limit Headers

Every response includes rate limit information in the headers:

  • • X-RateLimit-Limit - Your rate limit
  • • X-RateLimit-Remaining - Remaining requests
  • • X-RateLimit-Reset - Unix timestamp when limit resets

State Coverage

We provide complete coverage for all 50 US states with daily data updates from official government sources.

AL✓
AK✓
AZ✓
AR✓
CA✓
CO✓
CT✓
DE✓
FL✓
GA✓
HI✓
ID✓
IL✓
IN✓
IA✓
KS✓
KY✓
LA✓
ME✓
MD✓
MA✓
MI✓
MN✓
MS✓
MO✓
MT✓
NE✓
NV✓
NH✓
NJ✓
NM✓
NY✓
NC✓
ND✓
OH✓
OK✓
OR✓
PA✓
RI✓
SC✓
SD✓
TN✓
TX✓
UT✓
VT✓
VA✓
WA✓
WV✓
WI✓
WY✓

📊 Data Freshness

Tax rate data is automatically updated daily at 2:00 AM UTC. Each response includeslast_updated andsource_last_fetched timestamps.

Support

Need help? We're here for you.

📧 Email Support

Contact us at statetaxapi@gmail.com

Response time: 24-48 hours (Priority support available)

💬 Community

Join our developer community for discussions and updates

Discord, Slack, or GitHub Discussions (coming soon)

🐛 Report Issues

Found a bug or have a feature request?

GitHub Issues or direct email

✨ Best Practices

  • •Cache responses - Tax rates don't change frequently. Cache for at least 24 hours.
  • •Handle errors gracefully - Always check the success field in responses.
  • •Monitor your usage - Keep track of your API usage in the dashboard to avoid surprises.
  • •Use HTTPS only - Always make requests over HTTPS to protect your API key.
  • •Implement retry logic - Use exponential backoff for failed requests.