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_namefield in the response will contain the complete street address regardless of which request field was used.
Updated 11 months ago