Validate Addresses

ShipStation can validate the ship_to address when you purchase a label if you add the validate_address property to the request body using either the validate_only or validate_and_clean values. validate_and_clean is the default value for this property.

Currently, ShipStation API does not include a dedicated address validation endpoint. However, this feature is coming in 2025.

Requirements

Add the validate_address property to the purchase label request body (POST v2/labels)
Set the property value to the type of validation you require for the ship_to address: no_validation, validate_only, validate_and_clean

Sample Request

In this example, we add the validate_address property to the label request body with the validate_and_clean value.

POST /v2/labels

POST /v2/labels HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "validate_address": "validate_and_clean",
 "shipment":
    {
     "carrier_id": "se-28529731",
     "service_code": "usps_priority_mail",
     "ship_date": "2024-09-23T00:00:00.000Z",
     "ship_to":
        {
         "name": "John Doe",
         "phone": "+1 204-253-9411 ext. 123",
         "email": "example@example.com",
         "company_name": "My Company",
         "address_line1": "4301 Bull Creek Rd",
         "address_line2": "Suite 300",
         "city": "Austin",
         "state": "TX",
         "postal_code": "78731",
         "country_code": "US",
         "address_residential_indicator": "no",
        },
    "ship_from":
        {
         "name": "Jane Doe",
         "phone": "+1 204-253-9412",
         "email": "example1@example.com",
         "company_name": "My cool stuff",
         "address_line1": "710 West Ceasar Chavez St",
         "city": "Austin",
         "state": "TX",
         "postal_code": "78701",
         "country_code": "US",
         "address_residential_indicator": "no",
        },
    "warehouse_id": "se-28529731",
    "is_return": false,
    "confirmation": "none",
    "insurance_provider": "none",
    "packages":
        [
            {
             "package_id": "se-28529731",
             "package_code": "small_flat_rate_box",
             "weight":
               {
                "value": 1,
                 "unit": "pound"
                },
             "dimensions":
                {
                 "unit": "inch",
                "length": 8,
                "width": 8,
                "height": 9
               },
            "label_messages":
               {
                "reference1": null,
                "reference2": null,
                "reference3": null
               },
            "content_description": "Hand knitted wool socks",
           "products": [ ]
           }
       ],
    },
 "label_download_type": "url",
 "label_format": "pdf",
 "display_scheme": "label",
 "label_layout": "4x6",
}

If the address is fully validated and no changes are required, the response will be your standard response when creating a label. There are no additional properties to indicate the address validation status.

Response: Address Cleaned

If the validation finds a more precise address match in the available database, the shipment will simply include the updated ship_to address values. In this example, the validation added the +4 code to the postal_code property in the ship_to object.

{
 "ship_to":
    {
     "name": "John Doe",
     "phone": "+1 204-253-9411 ext. 123",
     "email": "example@example.com",
     "company_name": "My Company",
     "address_line1": "4301 Bull Creek Rd",
     "address_line2": "Suite 300",
     "city": "Austin",
     "state": "TX",
     "postal_code": "78731-5933",
     "country_code": "US",
     "address_residential_indicator": "no",
    },
},

Response: Address Validation Error

If the address cannot be validated, we’ll return an error and the label will not be created. The error will provide the details you need to locate the source of the validation issue so you can modify the address and attempt to create the label again.

{
    "request_id": "f0cab3d6-384e-4cce-9ba6-36f4e0de08f0",
    "errors": [
        {
            "error_source": "shipstation",
            "error_type": "business_rules",
            "error_code": "invalid_address",
            "message": "Invalid City, State, or Zip",
            "field_name": "ship_to",
            "detail_code": "unsupported_country"
        }
    ]
}

The level of detail provided in the message and details_code properties will vary depending on the country the address is located in and the validation level available.