Address Validation with UPS, FedEx and USPS

Address validation checks a street address against carrier and USPS reference data and hands back a standardized version of the address plus a list of suggestions. One addressvalidate call has the same request and response shape on every carrier that supports it, so you can switch between UPS, FedEx, USPS and Stamps.com without rewriting your integration.

It is a suggestion API, not a yes/no answer#

This is the single most common misunderstanding, so it is worth stating up front: address validation provided by UPS, FedEx and USPS does not tell you whether an address is real or whether a package will arrive. It returns a normalized address, zero or more alternative addresses, and a set of quality indicators. Treat it as address suggestion, and decide your own policy for what to do with a weak result.

All U.S. address validation traces back to United States Postal Service data. UPS and FedEx both use USPS data as their backend, so the three carriers return broadly similar results; the carriers layer their own extras on top, most usefully a residential/commercial classification.

From the UPS documentation:

UPS Address Validation uses U.S. Postal Service guidelines to thoroughly check the city, state and postal code of every shipment. UPS provides up to ten alternate addresses, including an accuracy rate that lets your customers know how closely the address they entered matches the suggested address.

Address validation is U.S.-only for most carriers. FedEx offers some international coverage, which RocketShipIt supports — see Supported Address Validation Countries.

Which carriers support address validation#

Every other carrier returns an error for the addressvalidate action — DHL, for example, has no address validation API. See Supported Shipping Carriers for the full carrier list.

What it can do#

• Complete an incomplete address. Validation can fill in missing pieces that can be inferred from the rest of the address. It cannot invent missing secondary information — an apartment or suite number — but it can tell you one is needed.
• Correct an invalid address. For example, fixing a postal code that disagrees with the street and city.
• Classify the address as business or residential, which materially changes your rates: a residential surcharge applies on most services. U.S. and Canada only.

Request#

{
  "carrier": "ups-rest",
  "action": "addressvalidate",
  "params": {
    "key": "your-key-from-authenticate-request",
    "to_name": "John Doe",
    "to_addr1": "2920 Zoo Drive",
    "to_city": "San Diego",
    "to_state": "CA",
    "to_code": "92112",
    "to_country": "US",
    "test": true
  }
}

Only the address fields matter here: to_name, to_addr1, to_addr2, to_addr3, to_city, to_state, to_code and to_country. Every one is described in Parameters.

Reading the response#

The full field list is in AddressValidate Response Format. In practice you are looking at five things:

A workable policy for most checkout flows:

1. match is true and there is one suggestion → use the suggested (standardized) address. It is the same address, spelled the way the carrier wants it, which reduces address-correction fees.
2. match is false and there are suggestions → present them and let the customer choose. Do not auto-apply a suggestion; validation regularly proposes a neighbouring building.
3. No suggestions and no match → keep the address the customer typed and ship at your own risk, or ask them to re-enter it.

Address correction fees are charged by the carrier after the fact, so the point of validating at checkout is to catch the problem while the customer is still on the page.

UPS#

UPS calls this the Street Level Address Validation (XAV) service, and it does two separable jobs. The request_option param picks which:

RocketShipIt defaults to 3 so a single call gives you a standardized address and the residential flag. When you send no to_addr1 it drops to 1 and asks UPS for a regional (city/state/ZIP) check only, which is the cheapest way to sanity-check a postal code you were given without a street.

UPS returns up to ten candidates. RocketShipIt promotes the first into the top-level addr1/city/state/zipcode fields and returns all of them in suggestions, each with its own residential and po_box flags. If UPS declines to confirm the address, city_state_zip_match still gets computed locally from a ZIP database, so you always get a city/state/ZIP answer.

Test environment: UPS restricts Street Level Address Validation to California (CA) and New York (NY) addresses when test is true. An address anywhere else will look broken in test and work in production. See test in Parameters.

FedEx#

FedEx does not return a list of alternative addresses the way UPS does. It runs the address through two steps:

1. Normalize — replace common roadway identifiers such as Street and Parkway with their standard abbreviations (ST, PKWY) and reorder components. If the input cannot be normalized, the effective address returned is the input address with a state of RAW, and non-address values are discarded. If you need those values, store them before submitting.
2. Standardize — find the actual address the input most likely meant. If standardization fails, the effective address is the normalized form with a state of NORMALIZED.

An address is likely good when FedEx returns the state Standardized together with the attributes Resolved = True and DPV = True.

RocketShipIt returns match as true for FedEx only when FedEx's address attributes report Resolved=True or DPV=True. The individual attributes come back in the checks array (check.type / check.result), so you can see exactly which test failed — for example MissingOrAmbiguousDirectional on an address missing its N/SW prefix.

USPS#

USPS validates against the ZIP+4 product file directly, which makes it the strictest of the three and the one that will tell you why an address failed.

• match and city_state_zip_match are set when USPS returns match code 31, meaning the address matched a ZIP+4 record exactly.
• The checks array carries the USPS delivery-point indicators: DPVConfirmation, DPVCMRA (a commercial mail receiving agency, i.e. a mailbox store), business, centralDeliveryPoint and vacant. A vacant address that still passes DPV is a real address nobody lives at — worth flagging in a fraud check.
• residential is the inverse of the business indicator.
• USPS corrections are surfaced as Warning entries in errors with the USPS code intact. The one you will see most is code 32, "apartment, suite, or box number needed" — the address exists, the unit does not, and the package will likely bounce.
• Sending only to_code and no street, city or state performs a city/state lookup: give it a ZIP, get back the city and state it belongs to.

Examples#

Runnable request/response pairs for every carrier are in the API Examples browser — see for instance UPS-REST Address Validation.

Related#

• Supported Address Validation Countries — which countries each carrier can validate in
• Parameters — every request parameter
• AddressValidate Response Format — the full response field list
• Shipping Country Codes — the country codes to put in to_country
• Rating — where the residential flag changes the price