Address Verification API: The Complete Guide

Every address a user types is a small bet, and a predictable share of those bets are wrong in ways that cost real money. A transposed digit bounces a package. A missing apartment number fails delivery even though the street is real. A UPS Store mailbox formatted as "Suite 214" sails through a basic check and lands on your homeowner mailing. A perfectly valid business address sits on a list you paid to reach houses. An address verification API is how you catch all of that in the same request where the address is captured. This is the practical guide: what these APIs actually return, where they quietly differ, how to pick one for your workflow, and how to wire it in without learning the edge cases the hard way.

What you actually get back

Skip the abstract description and look at a real response. You POST an address and read back JSON like this:

{
  "address": "20 Marie St, Iberia, MO 65486",
  "addressValid": true,
  "homeType": "SINGLE_FAMILY",
  "homeValue": 371000
}

Four fields, and each one drives a decision. addressValid is your first gate: false means the address did not resolve, so do not mail it and do not trust anything else in the row. homeType tells you what the property actually is, the field postal-only tools do not have. homeValue is a rough proxy for buying power. If the only field you ever read is addressValid, you are using a fraction of what a modern address API can tell you. Underneath, the service has also standardized the address, corrected the ZIP, and normalized the components, so two spellings of the same place collapse into one. Add ?expanded=true and the same call returns beds, baths, lot size, year built, tax assessment, and listing history.

The distinction that trips everyone up

The most expensive misunderstanding in this space is treating "valid" as if it means "a house I can sell to." Three different things get conflated:

• Deliverable. The postal service can drop mail here. A PO box, a UPS Store suite, and a warehouse are all perfectly deliverable.
• Residential. It is a home, not a business. A residential-versus- commercial flag gets you partway there.
• The right kind of home. A single-family house rather than an apartment, a vacant lot, or a duplex, and whether it sits in the value range you serve.

A CASS-certified postal API is excellent at the first and blind to the third. So if you are mailing homeowners and you filter on "valid" alone, you will pay to reach every deliverable PO box and storefront on the list. That is the exact failure mode behind filtering PO boxes and non-residential addresses, and it is why the property fields matter as much as the validity flag.

Where these APIs quietly differ

Every provider is strong in one of three areas and usually thin in the others. The common mistake is choosing by brand recognition instead of by the area you actually need:

• Postal and CASS. Deliverability, delivery point validation, ZIP+4, presort. The right pick when you are physically mailing at scale. This is where tools like Smarty and Lob live.
• Geocoding and global. Latitude and longitude, many-country coverage. The right pick when you need coordinates or international addresses. This is Google Address Validation's home turf.
• Property-aware. Returns the property type and value with the validation. The right pick when the address is a means to understanding the home and the person behind it.

No single API leads on all three, so the honest question is never "which is best" but "best for what." If you are weighing specific tools, the comparison pages keep fair, capability-by-capability breakdowns for Smarty, Melissa, Lob, and Google Address Validation, including where each one genuinely wins.

Why deliverability is not enough

Here is what property data changes in practice. A solar installer does not want every valid address. They want owner-occupied single-family homes above a certain value, because those are the ones that convert and finance. With a property-aware API they filter a raw list down to exactly that segment before spending a dollar on outreach: keep SINGLE_FAMILY, drop the apartments and lots, and sort by homeValue. A roofer keys on year built instead, because older homes are the ones that need roofs. Same API, different field, and neither move is possible with a deliverability-only check.

AddressVerify returns the property type (seven classes) and estimated value in the same call that validates the address, plus an expanded block on request. The two building blocks are classifying property type from an address and scoring leads by estimated home value, and together they turn a raw address into "is this a lead worth my time, and how much."

Choosing one: the question that actually decides it

Ignore the feature matrices for a minute and answer one question: what happens after the API responds? That single answer picks your category.

• If the next step is putting a physical mail piece in the stream, prioritize CASS and DPV. Property data will not save you a cent on postage compliance.
• If it is validating addresses across many countries, prioritize international coverage and geocoding.
• If it is deciding whether a lead is a homeowner worth a call, prioritize property type and value, because no amount of postal accuracy answers "is this a $600k single-family home."

Then test on your own data instead of a marketing table. A free tier exists so you can run a real sample and read the responses yourself. If you are migrating off something older, the USPS Web Tools API alternatives guide walks the swap, and Smarty vs Melissa vs AddressVerify compares the usual suspects head to head.

Wiring it in without hitting the edge cases the hard way

The happy path is one POST:

curl -X POST 'https://api.addressverify.io/service/lookup/address' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "address": "20 Marie St, Iberia, MO 65486" }'

That is the whole loop. The parts that actually bite you are the unhappy paths, so handle them up front rather than in a 2 a.m. incident:

• Put a timeout on it. In a checkout or signup flow, a verification call should never hang the form for more than a second or two. Wrap it, and decide in advance what happens if it is exceeded: usually accept the submission, flag it unverified, and re-check in a batch pass.
• A 422 is almost always a missing street number. It means the address could not be parsed, not that your integration is broken. Treat it as a prompt to fix the input, not a crash.
• An UNKNOWN home type is not a rejection. The address validated but the property could not be classified, which is common for new construction and rural parcels. Route those to review instead of auto-dropping real homes.
• A 429 means back off. You are over your rate limit. Retry with a short delay, and size your throughput against the plan's calls per second, not just the monthly cap.

For where to place the call in a funnel and the full request-path patterns, see the real-time address verification guide, and for the endpoint reference in five languages, the API documentation.

What it is actually worth

The return is easiest to see in mail. Send 10,000 pieces at 60 cents each, and if 12 percent are undeliverable, PO boxes, or non-residential, which is ordinary for an unscrubbed list, that is 1,200 wasted pieces and $720 per drop, before you count the responses you never got from the good addresses those bad rows crowded out. One pass through a verification API removes them for a small fraction of that. In a sales funnel the math is sharper still: a single truck roll or an hour of a rep's time chasing a bad or non-residential address costs more than thousands of lookups. The tool pays for itself on the first campaign, which is why cleaning at the source, covered in cleaning a marketing list, is usually the first integration teams ship.

Frequently asked questions

What does an address verification API actually return?

At minimum, whether the address is valid and its standardized form. A property- aware API like AddressVerify also returns the residential property type and an estimated value in the same response, and the full property detail on request.

Is it the same as CASS certification?

No. CASS is a specific USPS standard for bulk-mail address processing. Some verification APIs are CASS certified and some are not. AddressVerify focuses on residential property intelligence rather than postal certification, so if CASS compliance is a hard requirement, keep a CASS-certified tool in that part of the pipeline.

Real-time or batch?

Real-time when the result changes what happens next in the same session or webhook, like scoring a lead at capture. Batch when you are cleaning a list you already have. Most teams run both.

Does an UNKNOWN result mean I lose the lead?

Not necessarily. It means the address validated but the property could not be classified. Send those to a review queue rather than dropping them, because a share are real homes with thin underlying data.

Try it on your own addresses

The fastest way to see a property-aware response is the free address verifier tool, which runs the live API against anything you paste in. When you are ready to build, the API documentation has the full reference and code, and pricing is pay-as-you-go with 50 free lookups a month, so you can validate against your own list before you commit.