{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/addresses/validation","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/addresses/validation","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/addresses/validation","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Validate an Address","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"validate-an-address","__idx":0},"children":["Validate an Address"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipStation API cross references multiple databases to validate ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["addresses"]}," and identify potential deliverability issues."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ShipStation API 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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requirements","__idx":1},"children":["Requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The address validation endpoint is available to accounts in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://help.shipengine.com/hc/en-us/articles/19326509952027"},"children":["Advanced plan"]}," or higher."]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["TIP:"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"validate-addresses-on-the-free-plan","__idx":2},"children":["Validate Addresses on the Free Plan"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you are on the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://help.shipengine.com/hc/en-us/articles/19326486755867"},"children":["Free plan"]},", you can instead use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validate_address"]}," property in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/create-label"},"children":["Create Label"]}," or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/rates/estimate"},"children":["Get Rate"]}," calls to validate addresses. When validating with one of these methods, the call must include the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validate_address"]}," property and specify either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validate_only"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validate_and_clean"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-request--response","__idx":3},"children":["Example Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/addresses/validate"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is an example of a full request to the address verification service. The JSON body can validate up to 250 addresses per request."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/addresses/validate HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"US\"\n  }\n]\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Response"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response includes every address sent to the Address Validator, in the order it was received."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n  {\n    \"status\": \"verified\",\n    \"original_address\": {\n      \"name\": null,\n      \"phone\": null,\n      \"company_name\": null,\n      \"address_line1\": \"525 S Winchester Blvd\",\n      \"address_line2\": null,\n      \"address_line3\": null,\n      \"city_locality\": \"San Jose\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"unknown\"\n    },\n    \"matched_address\": {\n      \"name\": null,\n      \"phone\": null,\n      \"company_name\": null,\n      \"address_line1\": \"525 S WINCHESTER BLVD\",\n      \"address_line2\": \"\",\n      \"address_line3\": null,\n      \"city_locality\": \"SAN JOSE\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128-2537\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"no\"\n    },\n    \"messages\": []\n  }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-statuses","__idx":4},"children":["Response Statuses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field in the response can have one of the following four statuses:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"status"},"children":["status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"description"},"children":["description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verified"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Address was successfully verified."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unverified"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Address was not verified against the database because pre-validation failed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warning"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The address was validated, but could have formatting issues and should be double checked."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The address could not be validated with any degree of certainty against the database."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-verified-status","__idx":5},"children":["Example: Verified Status"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/addresses/validate HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"US\"\n  }\n]\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-unverified-status","__idx":6},"children":["Example: Unverified Status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This issue is with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country_code"]}," value of \"USA\" rather than the approved 2-charater ISO country code \"US\"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/addresses/validate HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"USA\"\n  }\n]\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-warning-status","__idx":7},"children":["Example: Warning Status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This issue is with the entire address, while correct, being contained in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address_line1"]}," field."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/addresses/validate HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n[\n  {\n    \"address_line1\": \"Studio Tour Drive, Leavesden WD25 7LR, UK\",\n    \"country_code\": \"GB\"\n  }\n]\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-error-status","__idx":8},"children":["Example: Error Status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This address cannot be verified because the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postal_code"]}," is incorrect."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/addresses/validate HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n[\n  {\n    \"address_line1\": \"Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"78756\",\n    \"country_code\": \"US\"\n  }\n]\n","lang":"http"},"children":[]}]},"headings":[{"value":"Validate an Address","id":"validate-an-address","depth":1},{"value":"Requirements","id":"requirements","depth":2},{"value":"Validate Addresses on the Free Plan","id":"validate-addresses-on-the-free-plan","depth":3},{"value":"Example Request & Response","id":"example-request--response","depth":2},{"value":"Response Statuses","id":"response-statuses","depth":2},{"value":"Example: Verified Status","id":"example-verified-status","depth":3},{"value":"Example: Unverified Status","id":"example-unverified-status","depth":3},{"value":"Example: Warning Status","id":"example-warning-status","depth":3},{"value":"Example: Error Status","id":"example-error-status","depth":3}],"frontmatter":{"seo":{"title":"Validate an Address"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/addresses/validation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}