Public Forms - Silent Verification Mode

Last updated: 2026-03-22

Overview

Silent verification mode is designed for public-facing forms - checkout flows, registration pages, shipping address entry - where showing a standardization comparison dialog or a "Verify Address" button is inappropriate for end users.

When enabled, address verification runs automatically on model save. Results are stored directly on the address record (is_verified, needs_review, verification_metadata) with no user interaction required.

Setup

Add to your .env:

ADDRESS_VERIFICATION_MODE=silent
ADDRESS_VERIFICATION_PROVIDER=auto

That's it. The address form will automatically:

• Hide the "Verify Address" button
• Suppress the standardization comparison dialog
• Run verification on every Address::create() and Address::update() (when address fields change)
• Store verification results directly on the model

How It Works

1. User fills out the address form and submits
2. The AddressVerificationObserver fires on creating / updating
3. It calls AddressProcessingService::verifyFromComponents() with context 'silent_save'
4. On success: is_verified=true, standardized fields applied, coordinates geocoded if missing
5. On failure: is_verified=false, needs_review=true - flagged for staff review

Reviewing Flagged Addresses

Addresses that fail silent verification are flagged with needs_review=true. Staff can find these in the admin panel:

• The Address resource table shows a "Needs Review" badge
• Filter by needs_review = true to see all flagged addresses
• Open the address to manually verify or correct it

Configuration Options

Key	Values	Default	Description
ADDRESS_VERIFICATION_MODE	interactive, silent	interactive	Verification UI mode
ADDRESS_VERIFICATION_ENABLED	true, false	true	Master switch for all verification
ADDRESS_VERIFICATION_PROVIDER	auto, usps, smarty, google, loqate*, none	auto	Which provider to use

* Loqate is not yet implemented; setting loqate will fall back to geocoding with a warning.

Security Considerations

Rate Limiting

Public forms are exposed to the internet. Each address save triggers an API call to your verification provider. Consider:

• Rate-limit your form endpoint using Laravel's throttle middleware
• Use CAPTCHA (reCAPTCHA, Turnstile) to prevent automated submissions
• Monitor API costs via the Address Audit Log resource in the admin panel

Example throttle middleware in routes/web.php:

Route::post('/checkout/address', AddressController::class)
    ->middleware('throttle:30,1'); // 30 requests per minute

Provider Costs

Silent mode runs verification on every save. Be aware of per-call costs:

• USPS: Free (US addresses only)
• Smarty: Paid per lookup
• Google Address Validation: Paid per request
• Loqate: Paid per lookup (Loqate is not yet implemented)

For high-traffic public forms, pin US addresses to the free USPS provider:

// config/addresses.php
'verification' => [
    'country_providers' => [
        'US' => 'usps',
    ],
],

USPS verification can be configured to fall back to queued jobs or geocoding once the hourly quota is reached. See the CONFIGURATION-GUIDE to learn how to enable these behaviors.

Minimal Example

# .env for a US checkout form
ADDRESS_VERIFICATION_MODE=silent
ADDRESS_VERIFICATION_PROVIDER=usps
USPS_CONSUMER_KEY=your-key
USPS_CONSUMER_SECRET=your-secret
GOOGLE_MAPS_SERVER_KEY=your-key  # For geocoding coordinates

Observer Guards

The AddressVerificationObserver has guards to prevent unnecessary API calls:

• Skips when ADDRESS_VERIFICATION_MODE is not silent
• Skips when ADDRESS_VERIFICATION_ENABLED is false
• Skips when address_line_1 is empty
• Skips when country_code is empty
• Skips when is_verified=true and no address fields changed
• Skips during re-entrant saves (prevents double-verification)

v1.1: Standalone Livewire Component (deferred)

A <livewire:filament-address-pro::address-form /> component is tracked for v1.1, enabling the full address input experience (country-aware fields, geocoding, autocomplete) in any Laravel/Livewire layout without a Filament panel.

The service layer is already UI-agnostic: AddressVerificationObserver fires on any Address model save, whether from a Filament form, a standalone Livewire component, an API controller, or an Artisan command. Silent verification works automatically.

v1.0 public-form pattern: Until the standalone component ships, embed the Filament address form in a minimal panel (or use a controller to save Address records directly) and rely on ADDRESS_VERIFICATION_MODE=silent for background verification on save.