Call the Smarty US Street Address API via POST https://us-street.api.smarty.com/street-address with auth-id and auth-token query parameters; send the address fields in the request body including street, city, state, and zipcode
Check the dpv_match_code in the components response: Y is a full match, S is a partial match (secondary address data required), D is missing secondary, blank means not deliverable; treat S and D as requiring user correction before label purchase
Inspect the rdi (Residential Delivery Indicator) field: R indicates residential, C indicates commercial; map this to the carrier's residential surcharge flag in your label request to avoid post-invoice adjustments
Read the dpv_vacant field: if Y, the address is USPS-confirmed vacant; suppress label generation and flag for manual review to avoid delivering to known vacant properties
Extract the ZIP+4 from the components object and store it with the validated address; use the ZIP+4 in carrier label requests where accepted to improve sortation accuracy and reduce address correction surcharges
Cache validation results keyed by normalized (street + ZIP) for a TTL of 30 days; re-validate on order submission if the cached result is older than TTL or if the address has been modified since the last validation
Known gotchas
Smarty's deliverability confirmation only reflects USPS delivery point data; an address that is USPS-deliverable may still be undeliverable by UPS or FedEx Ground if it falls within a carrier-defined limited-access area such as a remote rural route or a gated community without a carrier agreement
Apartment addresses missing a unit number receive a dpv_match_code of D (missing secondary) but the Smarty API still returns a ZIP+4; purchasing a label with a ZIP+4 for an address with missing secondary data does not fix the deliverability issue and the carrier may return the package
International address validation requires the Smarty International Street API with a different endpoint and authentication scope; sending a non-US address to the US Street Address API returns a 400 error or an empty candidates array, not a validation result
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp