Address validation API: why it matters
An address validation API checks whether a shipping address is real, deliverable, and correctly formatted before you spend money on a label. You send an address, and the API returns a standardized version, a deliverability verdict, and often corrections or a confidence score. That one call, made before you rate or buy a label, prevents the single most expensive category of shipping errors: packages sent to addresses that do not exist or cannot receive a delivery. This guide explains why address validation matters, how the API works, and where to put it in your flow.
It is part of our hub on shipping APIs for developers. For the wider picture, see what is a shipping API.
Why address validation matters
A bad address is not a small problem. It cascades into surcharges, failed deliveries, returns, reshipments, and refund requests, and it does all of that after you have already paid for a label. The costs stack up:
- Carrier correction surcharges. Many carriers charge a fee when they have to fix or interpret a bad address. These add up fast at volume.
- Failed deliveries and returns. An undeliverable package comes back, and you pay to ship it twice or refund the order.
- Support load. "Where is my order" tickets spike when packages get stuck on address exceptions.
- Bad rate quotes. A wrong postal code can produce a wrong rate, so the price you quoted is not the price you pay.
Validating an address costs a fraction of a cent. A single failed delivery, surcharge, and reship can cost several dollars. Address validation is one of the highest-return checks you can add to a shipping flow.
How an address validation API works
You send the raw address, and the API compares it against authoritative postal reference data, then returns a cleaned-up result with a verdict. The examples below are generic illustrative pseudo-REST to show the pattern, not the exact Expership contract; confirm the real endpoint and fields at /developers.
POST /addresses/validate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"street1": "1600 Amphitheatre Pkwy",
"city": "Mountan View",
"state": "CA",
"postal_code": "94043",
"country": "US"
}The response standardizes the address and flags what it changed:
{
"status": "corrected",
"deliverable": true,
"address": {
"street1": "1600 Amphitheatre Pkwy",
"city": "Mountain View",
"state": "CA",
"postal_code": "94043-1351",
"country": "US"
},
"corrections": ["city", "postal_code"],
"residential": false
}Notice what happened: the misspelled city was corrected, the postal code was extended to its full form, and the address was classified as commercial. Field names and status values vary by provider, so check the reference at /developers.
Verdicts you will get back
| Verdict | Meaning | What to do |
|---|---|---|
| valid | Deliverable as entered | Proceed |
| corrected | Deliverable after standardization | Use the returned address; optionally confirm with the buyer |
| ambiguous | Matches more than one real address | Ask the buyer to choose or clarify |
| undeliverable | No deliverable match found | Block and prompt for a correction before shipping |
Where to put validation in your flow
Validation pays off most when you do it early, before money is committed. Two good places:
- At address entry (checkout). Validate as the buyer types or on form submit. Catching the error while the customer is present means they fix it themselves, which is the cheapest correction of all.
- Before rating and buying a label. As a server-side gate, validate before you call the rate API or buy a label. This ensures a clean, deliverable address underlies the rate you quote and the label you print, and it heads off the tracking exceptions covered in our tracking guide.
Residential versus commercial classification
Beyond deliverability, validation often tells you whether an address is residential or commercial. That matters because many carriers charge more for residential delivery, so knowing the classification lets you rate accurately and avoid a surprise surcharge on the invoice. Feeding the correct residential flag into your rate call is a small step that keeps your quotes honest.
Practical tips
- Do not silently overwrite. When the API corrects an address, show the buyer the corrected version and let them confirm. Silent changes can send a package to the wrong place if the correction guessed wrong.
- Handle ambiguous explicitly. Ambiguous is not a failure; it means you need one more piece of information. Prompt for it rather than picking one at random.
- Store the standardized form. Save the cleaned address so downstream rating, labeling, and tracking all use the same canonical version.
- Validate internationally too. Formats and reference data differ by country. Confirm coverage for the countries you ship to.
Clean addresses also feed directly into lower costs. Fewer corrections and failed deliveries is one of the most durable ways to reduce shipping costs.
Getting started with Expership
Expership offers a multi-carrier shipping API for ecommerce sellers and consolidators shipping into the U.S. Explore the reference at /developers, see the full platform, or create an account to start testing. For the bigger picture, read what is shipping software and multi-carrier shipping explained.
Frequently asked questions
What is an address validation API?
It is a service that checks a shipping address against authoritative postal data and returns a standardized, deliverable version along with a verdict such as valid, corrected, ambiguous, or undeliverable. You call it before rating or buying a label to catch bad addresses early.
Why validate addresses before shipping?
Because a bad address causes carrier correction surcharges, failed deliveries, returns, reshipments, and support tickets, all after you have already paid for the label. Validation costs a fraction of a cent and prevents errors that cost several dollars each.
Where should address validation happen?
Ideally in two places: at checkout as the buyer enters the address, so they can fix mistakes themselves, and again server-side before you rate or buy a label, as a gate that guarantees a clean address underlies the shipment.
What does a corrected verdict mean?
It means the address was not deliverable exactly as entered but became deliverable after standardization, such as fixing a misspelled city or completing a postal code. Use the returned address, and it is good practice to show the correction to the buyer for confirmation.
Does address validation tell me if an address is residential?
Often yes. Many validation responses classify the address as residential or commercial. That is useful because carriers frequently charge more for residential delivery, so passing the correct flag into your rate call keeps quotes accurate.