Validate an Address | ShipEngine

ShipEngine is becoming ShipStation API

Over the next few months you'll notice the ShipEngine website, documentation portal, and dashboard being rebranded as ShipStation API. For our ShipEngine customers, you don't need to take any action or change any of your integrations in any way. All endpoints will remain the same and continue to function as they always have.

To learn more about what's coming, review our New ShipStation API page.

Validate an Address

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 addresses and identify potential deliverability issues.

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.

Requirements

The address validation endpoint is available to accounts in the Advanced plan or higher.

TIP:

Validate Addresses on the Free Plan

If you are on the Free plan, you can instead use the validate_address property in the Create Label or Get Rate calls to validate addresses. When validating with one of these methods, the call must include the validate_address property and specify either validate_only or validate_and_clean.

Example Request & Response

POST /v1/addresses/validate

This is an example of a full request to the address verification service. The JSON body can validate up to 250 addresses per request.

POST /v1/addresses/validate HTTP/1.1

[\
  {\
    "address_line1": "525 S Winchester Blvd",\
    "city_locality": "San Jose",\
    "state_province": "CA",\
    "postal_code": "95128",\
    "country_code": "US"\
  }\
]

Example Response

The response includes every address sent to the Address Validator, in the order it was received.

[\
  {\
    "status": "verified",\
    "original_address": {\
      "name": null,\
      "phone": null,\
      "company_name": null,\
      "address_line1": "525 S Winchester Blvd",\
      "address_line2": null,\
      "address_line3": null,\
      "city_locality": "San Jose",\
      "state_province": "CA",\
      "postal_code": "95128",\
      "country_code": "US",\
      "address_residential_indicator": "unknown"\
    },\
    "matched_address": {\
      "name": null,\
      "phone": null,\
      "company_name": null,\
      "address_line1": "525 S WINCHESTER BLVD",\
      "address_line2": "",\
      "address_line3": null,\
      "city_locality": "SAN JOSE",\
      "state_province": "CA",\
      "postal_code": "95128-2537",\
      "country_code": "US",\
      "address_residential_indicator": "no"\
    },\
    "messages": []\
  }\
]

Response Statuses

The status field in the response can have one of the following four statuses:

status	description
`verified`	Address was successfully verified.
`unverified`	Address was not verified against the database because pre-validation failed.
`warning`	The address was validated, but could have formatting issues and should be double checked.
`error`	The address could not be validated with any degree of certainty against the database.

Example: Verified Status

POST /v1/addresses/validate HTTP/1.1

[\
  {\
    "address_line1": "525 S Winchester Blvd",\
    "city_locality": "San Jose",\
    "state_province": "CA",\
    "postal_code": "95128",\
    "country_code": "US"\
  }\
]

Example: Unverified Status

This issue is with the country_code value of "USA" rather than the approved 2-character ISO country code "US".

POST /v1/addresses/validate HTTP/1.1

[\
  {\
    "address_line1": "525 S Winchester Blvd",\
    "city_locality": "San Jose",\
    "state_province": "CA",\
    "postal_code": "95128",\
    "country_code": "USA"\
  }\
]

Example: Warning Status

This issue is with the entire address, while correct, being contained in the address_line1 field.

POST /v1/addresses/validate HTTP/1.1

[\
  {\
    "address_line1": "Studio Tour Drive, Leavesden WD25 7LR, UK",\
    "country_code": "GB"\
  }\
]

Example: Error Status

This address cannot be verified because the postal_code is incorrect.

POST /v1/addresses/validate HTTP/1.1

[\
  {\
    "address_line1": "Winchester Blvd",\
    "city_locality": "San Jose",\
    "state_province": "CA",\
    "postal_code": "78756",\
    "country_code": "US"\
  }\
]