Resources

Addresses

Every label needs a sender + recipient address. The shape is the same everywhere; this page documents the fields, how verification works, and how to bulk-verify before quoting.

Address shape

namestring
Recipient or sender name. Required for toAddress, optional for fromAddress (we fall back to your account business name).
companystring
Business name. Optional. Used for commercial address detection — addresses with a non-empty company field are more likely to be classified as commercial by the carrier.
street1stringrequired
Primary street address line.
street2string
Apartment, suite, floor, etc.
citystringrequired
City name. Case-insensitive.
statestringrequired
Two-letter state / province code. Examples: CA, NY, ON, BC. Empty string for countries without a province subdivision.
zipstringrequired
Postal code. For US zip+4 (94103-1234) is accepted but not required.
countrystringrequired
Two-letter ISO-3166-1 alpha-2 country code. US, CA, GB, etc. Required even for domestic shipments.
phonestring
Recipient phone, in E.164 format ideally. Carriers require it for international and some express/overnight services.
emailstring
Recipient email. Used by carriers for delivery notifications when supplied.

Verify an address

POST/api/v1/addresses/verifyScope: write:addresses

Validate + standardise an address before using it on a label. Catches typos, missing apartment numbers, and addresses that won't deliver.

Verification runs the address through the carrier's USPS- certified address-validation database (US addresses) or the international postal partner (everything else). The response echoes back the standardised form — proper case, ZIP+4 appended, abbreviations expanded — plus a residential / commercial classification.

Request body

JSON

{
  "street1": "350 fifth avenue",
  "city": "new york",
  "state": "ny",
  "zip": "10118",
  "country": "US"
}

Response (200 OK)

JSON

{
  "verified": true,
  "isResidential": false,
  "verifiedAt": "2026-06-26T12:14:00Z",
  "verifiedMessage": "Address valid",
  "standardised": {
    "street1": "350 5TH AVE",
    "city": "NEW YORK",
    "state": "NY",
    "zip": "10118-0110",
    "country": "US"
  },
  "originalDeliverable": true
}

verifiedboolean
true when the address validates; false when the carrier rejected it.
isResidentialboolean
Carrier's commercial-vs-residential classification. Affects rates for UPS / FedEx (residential surcharge applies).
verifiedMessagestring
Human-readable validation result. When verified is false, this contains the reason.
standardisedobject
Carrier-canonical form of the address. Use this on the label if your customer accepts the changes.
originalDeliverableboolean
true if the address as supplied would deliver — even without applying the standardisation. Use this to decide whether to prompt the user to accept changes.

When to verify

Verify on collection (at checkout, address book add, etc.) rather than at label-buy time. Verification adds 300–800ms to the request — fine for an async flow, painful inside a synchronous buy.

We automatically run verification during /labels/quote and /labels/createeven if you didn't call this endpoint separately — but doing it upfront lets you surface standardisation prompts to your user before they hit checkout.

International addresses

state is the province / region code (ON for Ontario, QC for Quebec, NSW for New South Wales). For countries without a province subdivision (Belgium, Netherlands, etc.) pass an empty string.
zip formats vary widely (SW1A 1AA for UK, M5V 3L9 for Canada, 75008for France). Don't strip spaces.
phone is required by most international carriers for tariff + customs reasons.
Verification accuracy varies by country. Some countries (Japan, Germany) have national address databases the carriers query directly; others fall back to postal-code- only validation.

Error cases

422 invalid_zip— ZIP code doesn't exist or isn't valid for the given state.
422 undeliverable — the carrier flagged the address as confirmed-undeliverable (vacant, do-not-deliver, marked as a UPS/FedEx box on a residential street).
422 missing_field — one of the required fields is missing. Body includes missing.

See Errors for the full status-code reference.