Verify Address

Request

Validate and standardize a US shipping address against the address-service registry. Only the United States and its territories (PR, GU, VI, MP, MH, AS) are accepted — all other countries are rejected with HTTP 400.

How to interpret a 200 response

Use the errored and corrected together. Apply the rules in the order below — the first matching branch wins.

errored == true → Address is unusable
Do not use the response fields as a shipping address. Prompt the user to revise the input.
errored == false && corrected == true → Address is non-standard
The submitted address is not in its standard form — for example, the city name is misspelled, the ZIP code is wrong or incomplete, or street abbreviations / casing are off. The service was able to identify the intended address and return a standardized version. Strongly recommend the user update their address before shipping.
The response fields (street, street2, city, state, zip, country) carry the standardized address. Surface them to the user (along with corrections[] for context) and suggest adopting this version as the final shipping address. See the example below — the user typed the misspelled Bsoton, and the response returns the corrected Boston.
errored == false && corrected == false → Fully valid
The input matches the postal database exactly. Use it as-is — no confirmation needed.

Decision tree (pseudocode)

if (errored) {
  // Unusable — ask the user to revise
} else if (corrected) {
  // Usable — replace input with response fields,
  // optionally surface corrections[] for user confirmation
} else {
  // Fully valid — use as-is
}

Additional fields

residential — whether the delivery point is residential. Defaults to true when the downstream service cannot determine it.
corrections[].message / errors[].message — human-readable text suitable for direct display to end users.

Security

BearerAuth or ApiTokenAuth

Bodyapplication/jsonrequired

streetstringrequired

Primary street address.

Example:"123 Main St"

street2string

Secondary address line (apartment, suite, unit, etc.). Optional.

Example:"Apt 4B"

citystringrequired

City name.

Example:"San Francisco"

statestringrequired

Two-character state or territory code.

Example:"CA"

zipstringrequired

ZIP or postal code.

Example:"94105"

countrystringrequired

Country identifier. Only the United States and its territories are accepted. The value may be the ISO 3166-1 alpha-2 code (e.g., US, PR, GU, VI, MP, MH, AS) or a recognized country name (case-insensitive), such as United States, USA, Puerto Rico, Guam, US Virgin Islands, Northern Mariana Islands, Marshall Islands, or American Samoa. Other values are rejected with HTTP 400.

Example:"US"

curl -i -X POST \
  https://ps-api.shipsaving.com/api/addresses/verify \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "street": "123 Main St",
    "street2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "country": "US"
  }'

Responses

Address verification completed

Bodyapplication/json

streetstring

Standardized primary street address (or echo of input when not matched).

Example:"1 MAIN ST"

street2string

Standardized secondary address line (or echo of input when not matched).

Example:"STE 100"

citystring

Standardized city name (or echo of input when not matched).

Example:"ANYTOWN"

statestring

Standardized state or territory code.

Example:"CA"

zipstring

Standardized ZIP or postal code, typically expanded to ZIP+4 when matched.

Example:"90001-1234"

countrystring

Country code.

Example:"US"

residentialboolean

Whether the address is residential. Defaults to true when residential status cannot be determined.

Example:false

erroredboolean

true when the address is unusable — either not found, or matched but requiring additional information (e.g., apartment/suite number). See errors[] for details.

Example:false

correctedboolean

true when one or more fields were modified during standardization (e.g., corrected street spelling or ZIP code). See corrections[] for details.

Example:false

standardizedboolean or null

Example:true

correctionsArray of objects(AddressVerifyMessage)

Field-level corrections applied during standardization. Empty when no corrections were made.

Example:

[
  {
    "message": "Corrected ZIP Code"
  }
]

errorsArray of objects(AddressVerifyMessage)

Validation errors reported during address verification. Empty when the address is usable.

Example:

[]

Response

{
  "street": "1 MAIN ST",
  "street2": "STE 100",
  "city": "ANYTOWN",
  "state": "CA",
  "zip": "90001-1234",
  "country": "US",
  "residential": false,
  "errored": false,
  "corrected": false,
  "standardized": true,
  "corrections": [
    { … }
  ],
  "errors": []
}