Back to blog
laravel ux

The case for interactive address verification

November 18, 2026

Address verification APIs return a standardized version of the address you send them. Sometimes the difference is trivial — a missing postal code filled in, a street abbreviation expanded. Sometimes it's significant — a wrong street number corrected, a city name changed entirely.

Most implementations do one of two things with that result: silently overwrite the user's input, or ignore the standardized version and just set a is_verified flag. Neither is quite right.

The problem with silent overwriting

If you silently replace what the user typed with the standardized version, you've made a decision on their behalf without telling them. Usually that's fine. Occasionally it isn't.

Consider a user entering their own address — an address they know. The verification API returns a standardized version that differs in a way they don't recognize. Maybe the carrier database uses a different street name for their road. Maybe their building has an unofficial address that maps correctly to GPS but doesn't match the postal database. The API's version is "correct" by USPS or Smarty's definition; the user's version is what actually gets packages delivered to them.

If you overwrote silently, you've now stored an address the user doesn't recognize and may not be able to find on a map. The verification flag says the address is good. The delivery rate will tell you otherwise.

The problem with ignoring the result

The other extreme — capturing the verification result only as a flag and discarding the standardized address — wastes the most useful part of what you paid for. Verification APIs don't just validate; they correct. USPS DPV data can tell you that "123 Main St" should be "123 Main Street", that the postal code is wrong, or that the secondary unit number doesn't exist. Throwing that away means you're paying for validation and ignoring the correction.

A third option: show both and let the user choose

When a verified address differs from what the user typed, present them side by side and ask which to keep:

Your input              Suggested correction
─────────────────────   ──────────────────────────────
123 Main St             123 Main Street
Apt 4B                  APT 4B
New York, NY 10001      New York, NY 10001-1234

[Keep mine]             [Use suggested]

The user sees exactly what changed. They can accept the standardized version if it looks right, or keep their original if the "correction" is wrong for their situation.

This approach respects two things simultaneously: the user's knowledge of their own address, and the value of the verified data you retrieved. Neither is silently discarded.

When the difference is minor

Not every difference warrants interrupting the user. If the only change is a postal code extension (10001 → 10001-1234) or capitalisation (apt → APT), showing a comparison dialog adds friction for no meaningful benefit.

The practical solution is to apply insignificant corrections silently and show the dialog only when something substantive changed — a street name, a street number, a city. The definition of "substantive" is worth making explicit in your implementation:

protected function hasMeaningfulDifference(array $original, array $verified): bool
{
    $fields = ['address_line_1', 'city', 'state', 'postal_code'];

    foreach ($fields as $field) {
        $a = strtolower(trim($original[$field] ?? ''));
        $b = strtolower(trim($verified[$field] ?? ''));

        // Ignore postal code extensions (10001 vs 10001-1234)
        if ($field === 'postal_code') {
            $a = explode('-', $a)[0];
            $b = explode('-', $b)[0];
        }

        if ($a !== $b) {
            return true;
        }
    }

    return false;
}

Tracking what the user chose

The choice the user makes is worth storing alongside the verification result. If they consistently reject the standardized version for a particular address, that's a signal worth having. If they consistently accept it, you know the data is reliable.

The verification metadata can carry both:

'verification_metadata' => [
    'provider'          => 'usps',
    'verified_at'       => now()->toIso8601String(),
    'context'           => 'manual_entry',
    'original_input'    => $originalAddress,
    'standardized'      => $verifiedAddress,
    'user_choice'       => 'accepted_suggestion', // or 'kept_original'
],

This gives you an audit trail of not just whether an address was verified, but what the user decided when they saw the result.

The public-facing form case

The comparison dialog works well in admin panels where staff are entering addresses on behalf of customers. It's less appropriate on public-facing checkout forms, where interrupting the flow to ask a technical question about address standardization increases abandonment.

For public forms, a silent mode makes more sense: verify on save, store the result and the original, set needs_review = true if the standardized version differs significantly. Staff review flagged records later, in context, without the customer ever seeing the detail.

The same underlying logic runs in both cases — the difference is whether the choice is surfaced to the user immediately or deferred to a staff reviewer.

What you get

The comparison dialog doesn't require the user to understand what address verification is. It just shows them two versions of their address and asks which one looks right. Most users will accept the suggested version without thinking about it; the minority who reject it are usually right to do so.

The result is better data than silent overwriting (you didn't correct addresses that shouldn't have been corrected) and better data than ignoring the result (you did apply corrections the user agreed with). The audit trail tells you which is which.


The verification dialog described here is included in Filament Address Pro, alongside support for USPS, Google, and Smarty as verification providers. The silent mode and needs_review flag are both configurable per form instance.