Troubleshoot Address Validation Errors in AvaTax

Last updated
Save as PDF

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

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.
Please create a Support case online.

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.