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 object_state: "VALID" and object_source: "VALIDATOR".
  • 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 object_state: "INVALID" and object_source: "VALIDATOR". The Address object's messages field will contain an array of error messages 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.

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 object_purpose="PURCHASE" \
    -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(
    :object_purpose => "PURCHASE",
    :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(
    object_purpose = "PURCHASE",
    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(
    "object_purpose" => "PURCHASE",
    "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
resource.CreateAddress(new Hashtable(){
    {"object_purpose", "PURCHASE"},
    {"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_state": "INVALID", 
    "object_purpose": "PURCHASE", 
    "object_source": "VALIDATOR", 
    "object_created": "2015-03-30T23:47:11.574Z", 
    "object_updated": "2015-03-30T23:47:11.596Z", 
    "object_id": "67183b2e81e9421f894bfbcdc4236b16", 
    "object_owner": "admin", 
    "name": "Shawn Ippotle", 
    "company": "Shippo", 
    "street_no": "", 
    "street1": "215 CLAYTOON ST.", 
    "street2": "", 
    "city": "SAN FRANCISCO", 
    "state": "CA", 
    "zip": "94107", 
    "country": "US", 
    "phone": "", 
    "email": "", 
    "is_residential": null, 
    "ip": "", 
    "messages": [
            "source": "USPS",
            "code": "Unknown Street", 
            "text": "City, State and ZIP Code are valid, but street address is not a match."
    "metadata": ""

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