The CereTax Address Validation API supports standalone address validation for US addresses. This API attempts to validate and normalize the provided address and determine the address' physical location, up to rooftop-level precision. The results from the Address Validation API can be saved in your integration and used in create transaction requests to determine the appropriate taxing jurisdictions.
The following methods are supported by this API:
- GET (single address)
- POST (multiple addresses)
When submitting multiple addresses for validation, we recommend assigning a unique
locationCodeto each address so that you can easily identify the results of each address submitted in the request.
Each address submitted for validation must include one of the following field combinations:
- addressline1 + postalCode
- addressline1 + city + state
- freeformAddress
The address validation API will return an error under the following circumstances:
- The required address fields were not included in the request.
- The address submitted is invalid.
- A physical location could not be determined for the submitted address.
Examples
Successful Address Validation
POST /av.cert.ceretax.net/validate
[
{
"addressLine1": "3440 Preston Ridge Road",
"city": "Alpharetta",
"state": "GA"
}
]
In the response, you can see that CereTax was able to identify the address, populate the missing and normalized address details in the validatedAddressDetails object, and identify the location of the address with rooftop-level precision.
{
"results": [
{
"submittedAddressDetails": {
"addressLine1": "3440 Preston Ridge Road",
"addressLine2": "",
"city": "Alpharetta",
"state": "GA",
"postalCode": "",
"plus4": "",
"country": ""
},
"validatedAddressDetails": {
"addressLine1": "3440 PRESTON RIDGE RD",
"addressLine2": "",
"city": "ALPHARETTA",
"county": "Fulton",
"state": "GA",
"postalCode": "30005",
"plus4": "3817",
"country": "",
"fullAddress": "3440 PRESTON RIDGE RD ALPHARETTA GA 30005-3817"
},
"location": {
"latitude": 34.0723,
"longitude": -84.263344,
"plusCode": "866Q3PCP+WM",
"accuracyType": "Rooftop"
}
}
]
}
Freeform Address
In your address data is not in a structured format that can be easily parsed into the individual address fields, or includes additional information like company and building names, addressees, etc. it can be submitted for validation using the freeformAddress field. When submitting an address for validation using the freeformAddress field, pass the entire address string in this field. CereTax will attempt to parse and validate the address.
POST /av.cert.ceretax.net/validate
[
{
"freeFormAddress": "ceretax 3440 preston ridge lan, atlanta GA 30005"
}
]
If the address passed in the freeformAddress field can be parsed and successfully validated, the standard address validation response will be returned from CereTax, like the example below. If the addresses cannot be parsed or validated, the API will return an error message indicating why address validation was not successful.
{
"results": [
{
"submittedAddressDetails": {
"addressLine1": "",
"addressLine2": "",
"city": "",
"state": "",
"postalCode": "",
"plus4": "",
"country": "",
"freeformAddress": "ceretax 3440 preston ridge lane atlanta GA 30005"
},
"validatedAddressDetails": {
"addressLine1": "3440 PRESTON RIDGE RD",
"addressLine2": "",
"city": "ALPHARETTA",
"county": "Fulton",
"state": "GA",
"postalCode": "30005",
"plus4": "3817",
"country": "",
"fullAddress": "3440 PRESTON RIDGE RD ALPHARETTA GA 30005-3817"
},
"location": {
"latitude": 34.0723,
"longitude": -84.263344,
"plusCode": "866Q3PCP+WM",
"accuracyType": "Rooftop"
}
}
]
}
Invalid Address
In some cases, the address provided may be invalid or unidentifiable, but there is sufficient information in the request to provide an approximate physical location. In these cases, the Address Validation API will return an error indicating the address is invalid, but still provide the approximate location based on the available information.
POST /av.cert.ceretax.net/validate
[
{
"addressLine1": "123 Main Street",
"city": "Alpharetta",
"postalCode": "30005",
"state": "GA"
}
]
In the response below, you can see that CereTax determined that the address submitted was invalid but was able to provide an approximate location at the Zip5-level based on the postal code in the request. Although the location details in these cases can be used for tax calculation purposes, we recommend you review the submitted address to see if any updates can be made so that a valid address match with more precise location information can be determined.
{
"results": [
{
"submittedAddressDetails": {
"addressLine1": "123 Main Street",
"addressLine2": "",
"city": "Alpharetta",
"state": "GA",
"postalCode": "30005",
"plus4": "",
"country": ""
},
"validatedAddressDetails": {
"addressLine1": "",
"addressLine2": "",
"city": "",
"state": "",
"postalCode": "",
"plus4": "",
"country": ""
},
"location": {
"latitude": 34.07297,
"longitude": -84.29876,
"plusCode": "866Q3PF2+5F",
"accuracyType": "Zip5"
},
"errorMessages": [
{
"code": "3004",
"type": "Situs",
"message": "Invalid Address",
"summary": "The address provided is invalid. ",
"errors": null
}
]
}
]
}
Unknown Location
When a request is made to the Address Validation API with an invalid address and there is insufficient information to determine the address' location, an Unknown Location error will be returned.
POST /av.cert.ceretax.net/validate
[
{
"addressLine1": "123 Main Street",
"city": "Alpharetta",
"state": "NC"
}
]
The response below indicates that no location information could be identified for the provided address. In these cases, the address will need to be reviewed, updated, and resubmitted in order for an address match and location to be determined.
{
"results": [
{
"submittedAddressDetails": {
"addressLine1": "123 Main Street",
"addressLine2": "",
"city": "Alpharetta",
"state": "NC",
"postalCode": "",
"plus4": "",
"country": ""
},
"validatedAddressDetails": {
"addressLine1": "",
"addressLine2": "",
"city": "",
"state": "",
"postalCode": "",
"plus4": "",
"country": ""
},
"location": {
"latitude": 0,
"longitude": 0,
"plusCode": "",
"accuracyType": "Unknown"
},
"errorMessages": [
{
"code": "3003",
"type": "Situs",
"message": "Unknown Location",
"summary": "Latitude and longitude coordinates could not be determined for the address provided.",
"errors": null
}
]
}
]
}