Address Validation Messages

Message Types

The ShipEngine Address Validation service provides a "messages" object array that will provide you with detailed information about what changes were made to a cleansed address. Additionally, we surface detailed messaging around any errors that may have occurred during the validation process. There are 3 types of messages provided in the messages object:

Type Description
warning Warning messages will usually consist of significant changes* or additions to the data that was provided in the request
error Error messages will usually describe a portion of the data sent in the request, that could not be validated with any measure of accuracy
info Info messages will describe the partial or complete level of accuracy available for the Address Validation.

Note

Address Changes

We will not count the following alterations as a significant change to the address:

  • White spaces
  • Leading 0’s in a postal code
  • Diacritic equivalent (é vs e)
  • Abbreviations
  • Common variations
  • Standardizations

Validation Scope

It is important to note that there are different levels (scope) of validation that the ShipEngine Address Validation service is able to provide. A description of the Scope will be provided in the Validation messages as an "info" type message. For more information on the level of validation that we are able to provide for each country, please see the table on this page: Available Validation Levels by Country.

info

Partially Validated vs. Validated

Whenever a response provides you with a partial validation, it's important to note that the address could not be completely validated to the highest level of data available, and there will most likely be an error listed.

List of Messages

Here is a complete list of messages you can expect to see with our Address Validation endpoint.

Code Detail Code Message
a1001 unsupported_country This address is in a country that is not currently supported.
a1002 minimum_postal_code_verification_failed Could not verify this address to the postal code level.
a1002 street_does_not_match_unique_street_name Could not match the inputted street name to a unique street name. No matches or too many matches were found.
a1002 multiple_directionals The provided directionals (N, S, SW, etc.) and suffix (ST, RD, AVE) combination is incorrect and resulted in multiple records.
a1002 suite_not_valid The street address was found, but the suite number is invalid.
a1002 suite_missing The street address was found, but the suite number is missing.
a1002 invalid_house_number The value for house/building number is invalid.
a1002 missing_house_number The value for house/building number is missing.
a1002 invalid_box_number The value for PO (Post Office Box), RR (Rural Route), or HC (Highway Contract) box number is invalid.
a1002 missing_box_number The value for PO (Post Office Box), RR (Rural Route), or HC (Highway Contract) box number is missing.
a1002 suite_has_no_secondaries There was a suite number entered, but the location does not have secondaries (suites).
a1003 postal_code_changed_or_added There was a change or addition to the postal code.
a1003 state_province_changed_or_added There was a change or addition to the state/province.
a1003 city_locality_changed_or_added There was a change or addition to the locality name (city, municipality).
a1003 urbanization_changed There was a change to the dependent locality (urbanization).
a1003 street_name_spelling_changed_or_added There was a change or addition to the street name due to a spelling correction.
a1003 street_name_type_changed_or_added There was a change or addition to the street leading or trailing type, like from "St." to Rd.".
a1003 street_direction_changed_or_added There was a change or addition to the street pre-directional or post-directional, like from "N" to "S".
a1003 suite_type_changed_or_added There was a change or addition to the suite type, like from "STE" to "APT".
a1003 suite_unit_number_changed_or_added There was a change or addition to the suite/unit number.
a1003 double_dependent_locality_changed_or_added There was a change or addition to the double-dependent locality.
a1003 subadministrative_area_changed_or_added There was a change or addition to the sub-administrative area.
a1003 subnational_area_changed_or_added There was a change or addition to the sub-national area.
a1003 po_box_changed_or_added There was a change or addition to the PO Box.
a1003 premise_type_changed_or_added There was a change or addition to the premise type.
a1003 house_number_changed There was a change or addition to the house number.
a1003 organization_changed_or_added There was a change or addition to the organization.
a1004 partially_verified_to_state_level This address has been partially verified down to the administrative area/state level. This is NOT the highest level possible with the data provided.
a1004 partially_verified_to_city_level This address has been partially verified down to the city level. This is NOT the highest level possible with the data provided.
a1004 partially_verified_to_street_level This address has been partially verified down to the street level. This is NOT the highest level possible with the data provided.
a1004 partially_verified_to_premise_level This address has been partially verified down to the house/building level. This is NOT the highest level possible with the data provided.
a1007 verified_to_state_level This address has been verified down to the state level (highest possible accuracy with the provided data)
a1007 verified_to_city_level This address has been verified down to the city level (highest possible accuracy with the provided data)
a1007 verified_to_street_level This address has been verified down to the street level (highest possible accuracy with the provided data)
a1007 verified_to_premise_level This address has been verified down to the house/building level (highest possible accuracy with the provided data)
a1007 verified_to_suite_level This address has been verified down to the suite/PO box level (highest possible accuracy with the provided data)
a1008 coded_to_street_level This record was successfully geocoded to the street level (US ZIP+4, Canada full postal code)
a1008 coded_to_neighborhood_level This record was successfully geocoded to the neighborhood level (US ZIP+2)
a1008 coded_to_community_level This record was successfully geocoded to the community level (ZIP centroid in the US, 3 digit postal code for Canada)
a1008 coded_to_state_level This record was succesfully geocoded to the state or administrative area level.
a1008 coded_to_rooftop_level This record was successfully geocoded down to the rooftop level, meaning this point is within the property limits (most likely in the center).
a1008 coded_to_rooftop_interpolation_level This recored was succesfully geocoded down to the rooftop level through street coordinate interpolation. This point is most likely within or close to the property limits.