Tax Rates API

Easy REST API for sales tax rates by postal code or street address.

Request format

Authentication

Avalara uses API keys to allow access to the API. The API key is issued upon registering for an account. There are two formats to provide the API key.

FIRST OPTION: VIA AUTHORIZATION HEADER

The API key may be included in all API requests to the server in a header that looks like the following:

Authorization: AvalaraApiKey {apikey}

where {apikey} is replaced with your personal API key.

SECOND OPTION: USING A QUERY PARAM

You can pass the API key in the querystring as one of the parameters instead of passing it in a header. i.e:

https://taxrates.api.avalara.com:443/address?street=435+Ericksen+Ave+NE&city=Bainbridge%20Island&state=WA&postal=98110&apikey={apikey}

where {apikey} is replaced with your personal API key.

Example: Sales Tax Rate for a Postal Code(collapse)

Use the API to get the sales tax rate for a postal code in the US. This endpoint requires these parameters: country, postal.

$ curl 'https://taxrates.api.avalara.com:443/postal?country=usa&postal=98110' \
    -H "Authorization: AvalaraApiKey {apiKey}"
    

Example: Sales Tax Rate for a Street Address(collapse)

Use the API to get the sales tax rate for a business or residential street address in the US. This endpoint requires these parameters: country, state, postal, city, address.

$ curl 'https://taxrates.api.avalara.com:443/address?country=usa&state=wa&city=Bainbridge%20Island&postal=98110&street=100%20Ravine%20Lane%20NE' \
    -H "Authorization: AvalaraApiKey {apiKey}"
    

Parameters

A request is built from the following parameters. For the address endpoint, all parameters are required. The postal endpoint only requires the country and postal parameters.

street
first line of the address
Ex: "1101 Alaskan Way"
city
city of the address
Ex: “Seattle”, “Montreal”, “Bournemouth”
state
state or region of the address
Ex: “WA”, “QC”, “Washington”, “Quebec”
country
country code in ISO 3166-1 alpha-3 format
Ex: “USA”, “CAN”, “GBR”
postal:
postal code of the address
Ex: “98101”, “V8X 3X4”, “BH1 1AA”

Response format

Tax Rates returns a JSON object that contains a list of individual jurisdictions' tax rates, as well as a rate summary. This example shows the rates in Bainbridge Island, Washington:

Example(collapse)

{
    "totalRate": 0.086000,
    "rates": [
        {
            "rate": 0.021000,
            "name": "WA CITY TAX",
           "type": "city"
        },
        {
            "rate": 0.065000,
            "name": "WA STATE TAX",
            "type": "state"
        }
   ]
}

Attributes(collapse)

totalRate:
doubleContains the total tax rate for the location in question. Note that it is not a percentage; in the example above, the totalRate of 0.086 represents a tax rate of 8.6%.
rates:
rate arrayEach object in the rates array represents a single jurisdiction's contribution to the totalRate.
rate.rate:
doubleNote that a rate field may not always be present; in these cases, the contribution is 0.0%.
rate.name:
string
rate.type:
string

Errors

The TaxRates API uses the following error codes and messages:

Error Code
Message
400

Unable to resolve one or more document addresses

Value cannot be null. Parameter name: address

The postal code you provided was not valid. Please check your postal code before re-trying.

401

No authorization was provided. Please check the documentation to determine proper type for this API

The HTTP Authorization header you provided used an invalid scheme or the credentials were missing.

The credentials you provided were not accepted.

Your request provided two forms of authentication. Please check the documentation for the API to determine which form to use.

429

Rate limiting has been exceeded. Try again later.

Rate Limits

To ensure that the service is available for as many people as possible, we have a rate limit of 15 tax rate requests every 1 minute. If you get a response that you've exceeded the rate limit, we suggest waiting 60 seconds before making your next request.