Address Validation

Overview

In order to accurately determine the customer location, Taxamo provides an Address Validation service which 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.

Request

The following fields are used for US address validation.

Taxamo API	Type	Required	Description
buyer_name	String	No	See Example Product Tax Codes table below.
invoice_address.building_number invoice_address.street_name invoice_address.address_detail	String	Yes	Concatenated to form primary address line for validation. At least one of these must be supplied.
invoice_address.city	String	Yes	City
invoice_address.county	String	No	County or Urbanization for Puerto Rico and US Virgin Islands
invoice_address.region	String	Yes	State code
invoice_address.postal_code	String	Yes	ZIP or Zip+4 code (5 or 9 digits

Response

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

Taxamo API Field	Type	Description
invoice_address.lookup_result.found	Boolean	Returns true if the address was found. In that case, `found_data` will contain the best match for the provided address.
invoice_address.lookup_result.message	String	Any error message will be returned here. e.g. “Address not found”
invoice_address.lookup_result.found_data	Map	May 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_name	String	Firm name
\|- street_name	String	Primary address line from request.
\|- address_detail	String	Secondary address line if present in address database
\|- city	String	City
\|- county	String	County or Urbanization for Puerto Rico and US Virgin Islands
\|- region	String	State
\|- postal_code	String	Zip+4 e.g. “98101+1531”

Usage

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.

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