Address Validation


To accurately determine the customer location, the service provides an Address Validation feature that can check the provided invoice address against a database. The service assigns a confidence score to the validation and can correct minor spelling mistakes.

When available, the corrected address is returned in the response to /tax/calculate and /transactions requests.

Otherwise, the service will immediately respond with error_code set to “validation_error”.

In order to validate a US address without providing full location evidence set forced_country_code to “US” in the /tax/calculate request.


The following fields are used for US address validation.

Taxamo APITypeRequiredDescription
buyer_nameStringNoSee Example Product Tax Codes table below.


StringYesConcatenated to form primary address line for validation.

At least one of these must be supplied.


Urbanization for Puerto Rico and US Virgin Islands
invoice_address.regionStringYesState code
invoice_address.postal_codeStringYesZIP or Zip+4 code (5 or 9 digits


Address validation results are available in /tax/calculate and /transactions responses:

Taxamo API FieldTypeDescription
invoice_address.lookup_result.foundBooleanReturns true if the address was found. In that case, found_data will contain the best match for the provided address.
invoice_address.lookup_result.messageStringAny error message will be returned here. For example “Address not found”
invoice_address.lookup_result.found_dataMapMay be returned if the address validation service has a possible match.

The address here will include spelling and other corrections so it should be confirmed by the customer.
|- buyer_nameStringFirm name
|- street_nameStringPrimary address line from request.
|- address_detailStringSecondary address line if present in address database
|- cityStringCity
|- countyStringCounty


Urbanization for Puerto Rico and US Virgin Islands
|- regionStringState
|- postal_codeStringZip+4

For example “98101+1531”


Depending on how you capture the address you may have building number and street name in the same line. In this case, you can use building_number, street_name, or address_detail for the street address.



The lookup_result.found_data.street_name field in the response will contain the complete street address regardless of which request field was used.