Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipStation API cross references multiple databases to validate addresses and identify potential deliverability issues.
ShipStation API supports address validation for virtually every country on Earth, including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.
- The address validation endpoint is available to accounts in the Advanced plan or higher.
TIP:
If you are on the Free plan, you can instead use the
validate_addressproperty in the Create Label or Get Rate calls to validate addresses. When validating with one of these methods, the call must include thevalidate_addressproperty and specify eithervalidate_onlyorvalidate_and_clean.
POST /v1/addresses/validate
This is an example of a full request to the address verification service. The JSON body can validate up to 250 addresses per request.
POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
[
{
"address_line1": "525 S Winchester Blvd",
"city_locality": "San Jose",
"state_province": "CA",
"postal_code": "95128",
"country_code": "US"
}
]Example Response
The response includes every address sent to the Address Validator, in the order it was received.
[
{
"status": "verified",
"original_address": {
"name": null,
"phone": null,
"company_name": null,
"address_line1": "525 S Winchester Blvd",
"address_line2": null,
"address_line3": null,
"city_locality": "San Jose",
"state_province": "CA",
"postal_code": "95128",
"country_code": "US",
"address_residential_indicator": "unknown"
},
"matched_address": {
"name": null,
"phone": null,
"company_name": null,
"address_line1": "525 S WINCHESTER BLVD",
"address_line2": "",
"address_line3": null,
"city_locality": "SAN JOSE",
"state_province": "CA",
"postal_code": "95128-2537",
"country_code": "US",
"address_residential_indicator": "no"
},
"messages": []
}
]The status field in the response can have one of the following four statuses:
| status | description |
|---|---|
verified | Address was successfully verified. |
unverified | Address was not verified against the database because pre-validation failed. |
warning | The address was validated, but could have formatting issues and should be double checked. |
error | The address could not be validated with any degree of certainty against the database. |
POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
[
{
"address_line1": "525 S Winchester Blvd",
"city_locality": "San Jose",
"state_province": "CA",
"postal_code": "95128",
"country_code": "US"
}
]This issue is with the country_code value of "USA" rather than the approved 2-charater ISO country code "US".
POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
[
{
"address_line1": "525 S Winchester Blvd",
"city_locality": "San Jose",
"state_province": "CA",
"postal_code": "95128",
"country_code": "USA"
}
]This issue is with the entire address, while correct, being contained in the address_line1 field.
POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
[
{
"address_line1": "Studio Tour Drive, Leavesden WD25 7LR, UK",
"country_code": "GB"
}
]This address cannot be verified because the postal_code is incorrect.
POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
[
{
"address_line1": "Winchester Blvd",
"city_locality": "San Jose",
"state_province": "CA",
"postal_code": "78756",
"country_code": "US"
}
]