Skip to content
/Authentication

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

Get Access Token

Request

Issue a short-lived access token using the OAuth 2.1 Client Credentials grant.

Provide:

  • Authorization: Basic base64(AppKey:AppSecret)
  • Content-Type: application/x-www-form-urlencoded
Security
basicAuth
Bodyapplication/x-www-form-urlencodedrequired
grant_typestringrequired

Must be client_credentials.

Value"client_credentials"
scopestring

Optional space-delimited scopes.

Example: "API"
curl -i -X POST \
  -u <username>:<password> \
  https://x-api.shipsaving.us/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d scope=API

Responses

Access token issued

Bodyapplication/json
access_tokenstring

JWT access token.

token_typestring
Example: "Bearer"
expires_ininteger(int32)

Expiration time in seconds (default 1800).

scopestring

Granted scopes (if returned).

Response
application/json
{
  "access_token": "eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJTU19MSVZFX3RoNXE5S0pUZTBrdllsM3pRSFFmU0Q3NW5ETGlZQ2s4dlowSSIsImF1ZCI6IlNTX0xJVkVfdGg1cTlLSlRlMGt2WWwzelFIUWZTRDc1bkRMaVlDazh2WjBJIiwibmJmIjoxNzU0MzU1MzM0LCJjb21wYW55X2lkIjoiMTgyMyIsInVzZXJfaWQiOiIyNDA3Iiwic2NvcGUiOlsiQVBJIl0sImlzX3ZhbGlkIjp0cnVlLCJpc3MiOiJodHRwczovL3gtYXBpLnNoaXBzYXZpbmcudXMiLCJleHAiOjE3NTQzNTcxMzQsImlhdCI6MTc1NDM1NTMzNCwidGVzdF9tb2RlbCI6ZmFsc2V9.CsOfJozZUmd5cFrSodxGuDH0xxRQjau_qKwyOuJBPWigJeZXeoB_FgOl7r2kDfVndrru7IkXw5XCEmePkTJ25nyTD7RiysInBOuU0a89mfj4czedC8qHIHU-EI1CfRopHan2dCHfSog5skNT6edAmQfSNndj6mV18Pr0AclnhEgIG-CsfYkxZXRITXeqFKqiLfbUt8A4YsqT9zhXHqqttk42rBNzSddgBcBkHNGdys-qltEPc7xB_NpV02tZbsfl-hcHbHZYt_ufT4u4BLy5g7p6bd4Tt2vgUbRrVx-umCWuT3dad5di2Loj9vs2boywSCQshM1Aj4Fxzg8Sk-GsBw",
  "scope": "API",
  "token_type": "Bearer",
  "expires_in": 1799
}

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.