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 '
[
  {
    "name": "Mickey and Minnie Mouse",
    "phone": "714-781-4565",
    "company_name": "The Walt Disney Company",
    "address_line1": "500 South Buena Vista Street",
    "city_locality": "Burbank",
    "state_province": "CA",
    "postal_code": "91521",
    "country_code": "US"
  }
]'

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": "Mickey and Minnie Mouse",
      "phone": "714-781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "address_line2": null,
      "address_line3": null,
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US",
      "address_residential_indicator": "unknown"
    },
    "matched_address": {
      "name": "MICKEY AND MINNIE MOUSE",
      "phone": "714-781-4565",
      "company_name": "THE WALT DISNEY COMPANY",
      "address_line1": "500 S BUENA VISTA ST",
      "address_line2": "",
      "address_line3": null,
      "city_locality": "BURBANK",
      "state_province": "CA",
      "postal_code": "91521-0007",
      "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 '
[
  {
    "name": "Mickey and Minnie Mouse",
    "phone": "714-781-4565",
    "company_name": "The Walt Disney Company",
    "address_line1": "500 South Buena Vista Street",
    "city_locality": "Burbank",
    "state_province": "CA",
    "postal_code": "91521",
    "country_code": "US"
  }
]'

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 '
[
  {
    "name": "Mickey and Minnie Mouse",
    "phone": "714-781-4565",
    "company_name": "The Walt Disney Company",
    "address_line1": "500 South Buena Vista Street",
    "city_locality": "Burbank",
    "state_province": "CA",
    "postal_code": "91521",
    "country_code": "USA"
  }
]'

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 '
  [
    {
      "name": "",
      "phone": "",
      "company_name": "",
      "address_line1": "Studio Tour Drive, Leavesden WD25 7LR, UK",
      "city_locality": "",
      "state_province": "",
      "postal_code": "",
      "country_code": "GB"
    }
  ]'

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 '
  [
    {
      "name": "",
      "phone": "",
      "company_name": "",
      "address_line1": "London",
      "city_locality": "",
      "state_province": "",
      "postal_code": "",
      "country_code": "GB"
    }
  ]'