Address Validation

Overview

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.

Request

The following fields are used for US address validation.

FieldTypeRequiredDescription
buyer_nameStringNoName of the buyer.
invoice_address.building_number

invoice_address.street_name

invoice_address.address_detail
StringYesConcatenated to form primary address line for validation.

At least one of these must be supplied.
invoice_address.cityStringYesCity
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

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

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

or

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

For example “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

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