Site Logo

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:

TypeDescription
warningWarning messages will usually consist of significant changes* or additions to the data that was provided in the request
errorError messages will usually describe a portion of the data sent in the request, that could not be validated with any measure of accuracy
infoInfo messages will describe the partial or complete level of accuracy available for the Address Validation.

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.

List of Messages

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

CodeDetail CodeMessage
a1001unsupported_countryThis address is in a country that is not currently supported.
a1002minimum_postal_code_verification_failedCould not verify this address to the postal code level.
a1002street_does_not_match_unique_street_nameCould not match the inputted street name to a unique street name. No matches or too many matches were found.
a1002multiple_directionalsThe provided directionals (N, S, SW, etc.) and suffix (ST, RD, AVE) combination is incorrect and resulted in multiple records.
a1002multiple_matchesThis address matches with multiple records, and there is not enough information provided to confidently match with a single record.
a1002suite_not_validThe street address was found, but the suite number is invalid.
a1002suite_missingThe street address was found, but the suite number is missing.
a1002invalid_house_numberThe value for house/building number is invalid.
a1002missing_house_numberThe value for house/building number is missing.
a1002invalid_box_numberThe value for PO (Post Office Box), RR (Rural Route), or HC (Highway Contract) box number is invalid.
a1002missing_box_numberThe value for PO (Post Office Box), RR (Rural Route), or HC (Highway Contract) box number is missing.
a1002missing_cmra_or_private_mail_box_numberThis address is a Commercial Mail Receiving Agency (CMRA) and the Private Mail Box (PMB or #) is missing.
a1002suite_has_no_secondariesThere was a suite number entered, but the location does not have secondaries (suites).
a1002nullInvalid City, State, or Zip
a1002nullSuite / Apt Number Not Found or Invalid
a1003postal_code_changed_or_addedThere was a change or addition to the postal code.
a1003state_province_changed_or_addedThere was a change or addition to the state/province.
a1003city_locality_changed_or_addedThere was a change or addition to the locality name (city, municipality).
a1003urbanization_changedThere was a change to the dependent locality (urbanization).
a1003street_name_spelling_changed_or_addedThere was a change or addition to the street name due to a spelling correction.
a1003street_name_type_changed_or_addedThere was a change or addition to the street leading or trailing type, like from "St." to Rd.".
a1003street_direction_changed_or_addedThere was a change or addition to the street pre-directional or post-directional, like from "N" to "S".
a1003suite_type_changed_or_addedThere was a change or addition to the suite type, like from "STE" to "APT".
a1003suite_unit_number_changed_or_addedThere was a change or addition to the suite/unit number.
a1003double_dependent_locality_changed_or_addedThere was a change or addition to the double-dependent locality.
a1003subadministrative_area_changed_or_addedThere was a change or addition to the sub-administrative area.
a1003subnational_area_changed_or_addedThere was a change or addition to the sub-national area.
a1003po_box_changed_or_addedThere was a change or addition to the PO Box.
a1003premise_type_changed_or_addedThere was a change or addition to the premise type.
a1003house_number_changedThere was a change or addition to the house number.
a1003organization_changed_or_addedThere was a change or addition to the organization.
a1004partially_verified_to_state_levelThis address has been partially verified down to the administrative area/state level. This is NOT the highest level possible with the data provided.
a1004partially_verified_to_city_levelThis address has been partially verified down to the city level. This is NOT the highest level possible with the data provided.
a1004partially_verified_to_street_levelThis address has been partially verified down to the street level. This is NOT the highest level possible with the data provided.
a1004partially_verified_to_premise_levelThis address has been partially verified down to the house/building level. This is NOT the highest level possible with the data provided.
a1004nullInsufficient or Incorrect Address Data
a1004nullAddress not found
a1004nullAddress Not Deliverable
a1005name_max_length_exceededMaximum length for property 'name' is 50.
a1005phone_max_length_exceededMaximum length for property 'phone' is 50.
a1005company_name_max_length_exceededMaximum length for property 'company_name' is 50.
a1005line1_min_max_lengthMinimum length for property 'address_line1' is 1 and maximum length is 50.
a1005city_locality_max_length_exceededMaximum length for property 'city_locality' is 50.
a1005state_province_max_length_exceededMaximum length for property 'state_province' is 50.
a1005invalid_postal_codeInvalid postal code.
a1005country_invalid_lengthLength of property 'country_code' must equal exactly 2.
a1005address_not_foundAddress not found.
a1007verified_to_state_levelThis address has been verified down to the state level (highest possible accuracy with the provided data).
a1007verified_to_city_levelThis address has been verified down to the city level (highest possible accuracy with the provided data).
a1007verified_to_street_levelThis address has been verified down to the street level (highest possible accuracy with the provided data).
a1007verified_to_premise_levelThis address has been verified down to the house/building level (highest possible accuracy with the provided data).
a1007verified_to_suite_levelThis address has been verified down to the suite/PO box level (highest possible accuracy with the provided data).
a1008coded_to_street_levelThis record was successfully geocoded to the street level (US ZIP+4, Canada full postal code).
a1008coded_to_neighborhood_levelThis record was successfully geocoded to the neighborhood level (US ZIP+2).
a1008coded_to_community_levelThis record was successfully geocoded to the community level (ZIP centroid in the US, 3 digit postal code for Canada).
a1008coded_to_state_levelThis record was successfully geocoded to the state or administrative area level.
a1008coded_to_rooftop_levelThis record was successfully geocoded down to the rooftop level, meaning this point is within the property limits (most likely in the center).
a1008coded_to_rooftop_interpolation_levelThis recored was successfully geocoded down to the rooftop level through street coordinate interpolation. This point is most likely within or close to the property limits.