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 Calculate tax and other requests from the transactions endpoint.

Otherwise, the service will respond with the error_code: “validation_error” field.

To validate a US address without providing full location evidence, use set force_country_code: "US" field in the /tax/calculate request.

Request Fields

The following fields are used for US address validation.

buyer_nameStringNoName of the buyer.


StringYesConcatenated to form primary address line for validation.

At least one of these must be supplied.
invoice_address.countyStringNoCounty or Urbanization for Puerto Rico and US Virgin Islands
invoice_address.regionStringYesState code
invoice_address.postal_codeStringYesZIP or Zip+4 code (5 or 9 digits)

Response Fields

Address validation results are available in Calculate tax response and other responses from the transactions endpoint.

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 or 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.