Skip to content
/
Address Validation

ShipSaving New Open API (v1.0.5)

Overview
License

Apache 2.0

Languages
Servers
Sandbox server

https://x-api.shipsaving.us/

Production server

https://x-api.shipsaving.com/

Authentication

Operations

Shipment

Operations

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.

Validation Rules

  1. Non-U.S. addresses
    If country != "US", the validation process is skipped (the API is designed for U.S. domestic addresses only).

  2. Errored results
    If errored = true, the errors array is returned and should be used directly as the error message(s).

  3. Corrected without errors
    If errored = false && corrected = true, use the returned address fields (street, street2, city, state, zip, country, residential) as the standardized address.

    • The corrections array provides machine-readable codes that indicate how to improve the original input for a better match.

  4. Standardized flag
    The field standardized indicates whether the returned address differs from the original input:

    • If identical, standardized = false.
    • If different (e.g., casing, ZIP+4 adjustments, or street corrections), then standardized = true.
Security
BearerAuth
Bodyapplication/jsonrequired
streetstringrequired

Primary street line (house number + street name).

Example: "17XXX Castleton Street"
street2string or null

Secondary address line (apt, suite, unit, etc.).

Example: "STE XXX"
citystringrequired

City or locality.

Example: "City Of XXXX"
statestring= 2 charactersrequired
Example: "CA"
zipstring^\d{5}(-?\d{4})?$required

ZIP or ZIP+4 (US). Accepts 5 or 9 digits, with optional dash.

Example: "91748-5761"
countrystring= 2 charactersrequired

Two-letter country code (ISO 3166-1 alpha-2).

Example: "US"
curl -i -X POST \
  https://x-api.shipsaving.us/api/address/validate \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "street": "17XXX Castleton Street",
    "street2": "STE XXX",
    "city": "City Of XXXX",
    "state": "CA",
    "zip": "91748-5761",
    "country": "US"
  }'

Responses

OK

Bodyapplication/json
codestringrequired

Result code.

Example: "ok"
msgstringrequired

Human-readable message.

Example: "ok"
dataobject(ValidatedAddress)required
data.​streetstringrequired

Standardized primary street line.

Example: "17XXX CASTLETON ST"
data.​street2string or null

Standardized secondary line, if available.

Example: null
data.​citystringrequired

Standardized city/locality (uppercase).

Example: "CITY OF INDUSTRY"
data.​statestringrequired
Example: "CA"
data.​zipstringrequired

Standardized ZIP or ZIP+4.

Example: "91748-1749"
data.​countrystringrequired

ISO 3166-1 alpha-2 country code.

Example: "US"
data.​residentialbooleanrequired

Whether the address is classified as residential.

Example: true
data.​erroredbooleanrequired

Whether validation encountered one or more errors.

Example: true
data.​correctedbooleanrequired

Whether any components were corrected by the validator.

Example: true
data.​standardizedbooleanrequired

Whether the address is fully standardized.

Example: false
data.​errorsArray of objects(AddressIssue)required

Validation errors discovered during processing.

Example: [{"code":"ADDRESS.SECONDARY.MISSING","message":"High-rise address missing secondary number."}]
data.​errors[].​codestringrequired

Machine-readable issue code.

Example: "ADDRESS.SECONDARY.MISSING"
data.​errors[].​messagestringrequired

Human-readable description of the issue.

Example: "High-rise address missing secondary number."
data.​correctionsArray of objects(AddressIssue)required

Applied corrections or suggestions.

Example: [{"code":"ADDRESS.COMPONENT.CHANGED","message":"An address component (i.e., directional or suffix only) was changed"}]
data.​corrections[].​codestringrequired

Machine-readable issue code.

Example: "ADDRESS.SECONDARY.MISSING"
data.​corrections[].​messagestringrequired

Human-readable description of the issue.

Example: "High-rise address missing secondary number."
Response
application/json
{
  "code": "ok",
  "msg": "ok",
  "data": {
    "street": "17800 CASTLETON ST",
    "street2": null,
    "city": "CITY OF INDUSTRY",
    "state": "CA",
    "zip": "91748-1749",
    "country": "US",
    "residential": true,
    "errored": true,
    "corrected": true,
    "standardized": false,
    "errors": [ … ],
    "corrections": [ … ]
  }
}
Copyright © 2025 ShipSaving. All Rights Reserved.