Address Validation

In order to prevent failed deliveries and address correction surcharges, validate your addresses through our API before you create labels.

  Currently only US and Australian addresses can be validated.

Address validation logic

The Shippo address validation method verifies an Address by checking if it exists in the USPS database. The following results are possible:

  • Address is valid: The source address is valid and unique. The API will return a new, cleaned address object with is_complete: true. Additionally, there is a key for validation_results that contains an object with the key is_valid: true and messages will be empty.
  • Address is invalid: The address validator has processed the address, but could not find a match. There are three possible reasons: address doesn't exist, the address isn't deliverable, or the address is too ambiguous. The API will return a new Address object with the validation_results key is_valid: false. The validation_results object's messages field will contain a string with further detail about why the validation failed.
  • Residential or Commercial: The address validator also returns whether the address is residential or commercial via the is_residential flag. If the residential/commercial type could not be determined, the value will be null.

It is also worth noting that if the address object you created is missing information necessary for creating a shipment, the is_complete field will be false.

How to validate addresses

Validating addresses is easy: simply add a parameter validate: true to your Address POST request.

curl \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d name="Shawn Ippotle" \
    -d company="Shippo" \
    -d street1="215 Clayton St." \
    -d city="San Francisco" \
    -d state="CA" \
    -d zip=94117 \
    -d country="US" \
    -d email=""\
    -d validate=true
address_from = Shippo::Address.create(
    :name => "Shawn Ippotle",
    :company => "Shippo",
    :street1 => "215 Clayton St.",
    :city => "San Francisco",
    :state => "CA",
    :zip => "94117",
    :country => "US",
    :email => "",
    :validate => true
address_from = shippo.Address.create(
    name = "Shawn Ippotle",
    company = "Shippo",
    street1 = "215 Clayton St.",
    city = "San Francisco",
    state = "CA",
    zip = "94117",
    country = "US",
    email = "",
    validate = True
$fromAddress = Shippo_Address::create( array(
    "name" => "Shawn Ippotle",
    "company" => "Shippo",
    "street1" => "215 Clayton St.",
    "city" => "San Francisco",
    "state" => "CA",
    "zip" => "94117",
    "country" => "US",
    "email" => "",
    "validate" => true
    "name":"Shawn Ippotle", 
    "street1":"215 Clayton St.",
    "city":"San Francisco",
    "validate": true
}, function(err, address) {
    // asynchronously called
HashMap<String, Object> addressMap = new HashMap<String, Object>();
addressMap.put("name", "Mr. Hippo");
addressMap.put("company", "Shippo");
addressMap.put("street1", "215 Clayton St.");
addressMap.put("city", "San Francisco");
addressMap.put("state", "CA");
addressMap.put("zip", "94117");
addressMap.put("country", "US");
addressMap.put("phone", "+1 555 341 9393");
addressMap.put("email", "");
addressMap.put("validate", "true");

Address createAddress = Address.create(addressMap);
resource.CreateAddress(new Hashtable(){
    {"name", "Mr. Hippo"},
    {"company", "Shippo"},
    {"street1", "215 Clayton St."},
    {"city", "San Francisco"},
    {"state", "CA"},
    {"zip", "94117"},
    {"country", "US"},
    {"phone", "+1 555 341 9393"},
    {"email", ""},
    {"validate", "true"}});

You will get a response in the following format:

    "object_created": "2015-03-30T23:47:11.574Z",
    "object_updated": "2015-03-30T23:47:11.596Z",
    "object_id": "67183b2e81e9421f894bfbcdc4236b16",
    "is_complete": false,
    "validation_results": {
        "is_valid": false,
        "messages": [
                "source": "USPS",
                "code": "Address Not Found",
                "text": "The address as submitted could not be found. Please check for excessive abbreviations in the street address line or in the City name."
    "object_owner": "",
    "name": "Shawn Ippotle",
    "company": "Shippo",
    "street_no": "",
    "street1": "215 HIPPO ST.",
    "street2": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94107",
    "country": "US",
    "phone": "",
    "email": "",
    "is_residential": null,
    "metadata": "",
    "test": true

Validate existing address objects

To validate existing addresses, simply append /validate to an address GET call:

curl \
    -H "Authorization: ShippoToken <API_TOKEN>"
shippo.address.validate("d799c2679e644279b59fe661ac8fa488", function(err, address) {
    // asynchronously called

This call returns the same response JSON as the sample response above.

Bypass address validation for label purchase (USPS, UPS, & LaserShip only)

When purchasing shipping labels you can bypass the carrier's built-in address validation by setting the Shipment object's Extra field bypass_address_validation to true.

You'll want to include this in the "extra" field in order to bypass:

  /* insert other required shipment fields */
  "extra": {
    "bypass_address_validation": true