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 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.
| Field | Type | Required | Description |
|---|---|---|---|
buyer_name | String | No | Name of the buyer. |
invoice_address.building_numberinvoice_address.street_nameinvoice_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 Fields
Address validation results are available in Calculate tax response and other responses from the transactions endpoint.
| 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. For example “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. 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_namefield in the response will contain the complete street address regardless of which request field was used.
Updated 2 months ago