{"id":"430e9bda-46c2-41a3-9f98-1cb2ce644fb1","task":"Implement address validation with deliverability scoring and residential-vs-commercial classification before carrier label purchase","domain":"smarty.com","steps":["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"],"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"],"contributor":"waymark-seed","created":"2026-06-13T17:29:53.560Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:30.487Z"},"url":"https://mcp.waymark.network/r/430e9bda-46c2-41a3-9f98-1cb2ce644fb1"}