Address Validation

API Reference

Address Validation

Request

The Address Validation API checks the validity of U.S. domestic addresses and returns standardized address components in accordance with USPS® addressing standards. This helps improve delivery accuracy, reduce undeliverable mail, and support consistent pricing for shipping and logistics.

Security

BearerAuth

Bodyapplication/jsonrequired

streetstringrequired

The number of a building along with the name of the road or street on which it is located.

Example:"xxxx Olive Street"

street2string

The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.

Example:"STE XXX"

citystringrequired

This is the city name of the address.

Example:"Los Angeles"

statestringrequired

For U.S. addresses, this field must be a valid two-letter state code (e.g., "CA" for California, "NY" for New York).
For non-U.S. addresses, there is no restriction on the value.

Example:"CA"

zip_codestringrequired

Postal code of an Address.

Example:"021XX"

countrystringrequired

2-letter code for country. This field’s value will be an ISO 3166-1 two-digit code.

Example:"US"

POST

/api/address/validate

curl -i -X POST \
  https://x-api.shipsaving.com/api/address/validate \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "street": "xxxx Olive Street",
    "street2": "STE XXX",
    "city": "Los Angeles",
    "state": "CA",
    "zip_code": "021XX",
    "country": "US"
  }'

Responses

Bodyapplication/json

codestring

Result code.

Example:"ok"

msgstring

Human-readable message.

Example:"ok"

dataobject(ValidatedAddress)

Response

{
  "code": "ok",
  "msg": "ok",
  "data": {
    "street": "17XXX Tremont ST",
    "street2": null,
    "city": "Los Angeles",
    "state": "CA",
    "zip": "02111-XXXX",
    "country": "US",
    "residential": true,
    "errored": true,
    "corrected": true,
    "standardized": false,
    "errors": [ … ],
    "corrections": [ … ]
  }
}