Troubleshoot Address Validation Errors in AvaTax
Overview
You want to know how address validation works within the Avalara AvaTax service.
How an address is validated
AvaTax service uses the USPS database of Validated addresses, as well as the Postal Addressing Standards used by the USPS. In addition to the Canada Post service.
AvaTax takes your address and compares it to a database of registered addresses in our system.
Errors occur when address information is missing, wrong, or the address hasn't been registered. When in doubt, check the address with AvaTax's tax calculator.
Incorrect address or conflicting info
If address information is incorrect or it closely matches multiple addresses, AvaTax provides an error requesting more information.
- Example of a bad address:
- 123 ABC Street East, New York City, SC, 12345
-
Zip Code 12345 is in a different city (Schenectady, not New York City)
-
Zip Code 12345 is in a different state (NY, not SC)
-
The above includes a zip code, city, and state that do not match each other, so we can't validate the address
-
- 123 ABC Street East, New York City, SC, 12345
We'll do our best to normalize the address and get a specific +4 Zip code, which involves fixing capitalization and directional info so it matches what's in the USPS database:
-
"900 winslow way, bainbridge island, 98110" becomes "900 Winslow Way E, Bainbridge Island, WA, 98110-2450"
Address hasn't been registered
New construction (within the previous 6 months) may not be added to our database.
If you think an address is missing:
- Check the address with AvaTax's tax calculator.
- including:
- Full street address (House/Apartment Number, Street, City, State/Province, Zip/Postal code)
- Image of location from an online map service (Google, Bing, MapQuest, etc.) showing the physical location pinpoint
Explicit vs Implicit validation in the API
If you're working with the AvaTax API, address validation differs based on the method used.
-
Explicit - When using validateAddress
-
An explicit validation occurs without a tax calculation
-
The tax call is passed to the the web service. During the same call (or port opening), results generate a normalized address if successful or an error message if it it fails
-
-
Implicit - When using getTax
-
An implicit validation occurs within a getTax tax calculation
-
When a getTax call is passed to the web service, the tax calculation engine uses the information you provide to resolve the address with the best possible address data
-
Implicit address validation follows this logic:
-
Address Validation Errors
Error | Description |
AddressError |
The address can't be found. Check your spelling and make sure you're providing a full address. |
AddressComponentError |
Directional or suffix information, such as "west" or "avenue", is wrong. Check that the directions or suffixes in your address are correct and ensure any street, city or state names are properly capitalized. (Ex: E Street) |
AddressNoStreetError |
The street can't be found. Check your spelling, and make sure that street actually exists within the zip code. |
AddressRangeError |
The address number is out of range. Check the house or apartment number on your address for typos. |
AddressStandardizedError |
The address has been standardized (meaning things like "Post Office Box" were converted to "PO Box"), but it still can't be validated for other reasons. Clean up your address so it meets USPS standards and try again. |
MultipleAddressMatchError |
More than one address exists within the zip code you specified. See if you can find a more specific zip code. For example, 27612-4384 for Raleigh, NC instead of only 27612. |
AddressUnknownStreetError |
An exact match for the street name can't be found. Check your spelling, and make sure that street actually exists within the zip code you used. |
AddressEarlyWarningSystemError | We're aware of the address, but it hasn't been added to the database just yet. Check with Avalara Support for an update. |
NonDeliverableAddressError |
The physical location of this address exists, but there aren't any homes on the street. This can happen near railroads or rivers where buildings can't be constructed. Check your address information to make sure you're using the most accurate location info. |
CountryError |
Unknown country name. Check your abbreviations. For many customers, it's US or CA. |
TaxAddressError |
Address is missing info, or the information entered is incorrect. Check for spelling, accidental spaces, or incorrect state/country abbreviations. |
JurisdictionNotFoundError JurisdictionError DestinationJurisdictionError OriginJurisdictionError |
The correct tax jurisdiction can't be determined. Check your zip codes and use the most specific one that you can find. For example, 98122-4916 in Seattle, WA instead of only 98122. |
PostalCodeError |
The zip or postal code is wrong or missing numbers. Check the numbers for typos, and look up your zip code to double-check the one that you're using is correct. |