Validate an Address

Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipEngine cross references multiple databases to validate addresses and identify potential deliverability issues.

tip

Available Countries

ShipEngine 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.

Example

POST /v1/addresses/validate

This is a full request you can make to the address verification service. The JSON body can take up to 250 addresses to validate per request

curl -iX POST https://api.shipengine.com/v1/addresses/validate \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
[
  {
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "US"
  }
]'
  • curl

The Address Validation Response is provided for 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": []
  }
]

Address Status Meanings

status description
verified Address was successfully verified.
unverified Address validation was not validated against the database because pre-validation failed.
warning The address was validated, but the address should be double checked.
error The address could not be validated with any degree of certainty against the database.

Samples

Verified Status

curl -iX POST https://api.shipengine.com/v1/addresses/validate \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
[
  {
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "US"
  }
]'
  • curl

Unverified Status

curl -iX POST https://api.shipengine.com/v1/addresses/validate \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
[
  {
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "USA"
  }
]'
  • curl

Warning Status

curl -iX POST https://api.shipengine.com/v1/addresses/validate \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
  [
    {
      "address_line1": "Studio Tour Drive, Leavesden WD25 7LR, UK",
      "country_code": "GB"
    }
  ]'
  • curl

Error Status

curl -iX POST https://api.shipengine.com/v1/addresses/validate \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
  [
    {
      "address_line1": "Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "78756",
      "country_code": "US"
    }
  ]'
  • curl