Skip to main content

​
Address Verification

Terra integrates with Smarty Streets to provide address autocomplete and USPS validation. This ensures accurate addresses for mail delivery—critical for government benefit programs.

​
How It Works

1

User Starts Typing

After 3 characters, address suggestions appear in real-time.
123 main
├── 123 Main Street, Seattle, WA 98101
├── 123 Main Avenue, Portland, OR 97201
└── 123 S Main Street, Denver, CO 80202
2

User Selects Suggestion

All address fields auto-populate with the standardized address:
  • Street: 123 Main Street
  • City: Seattle
  • State: WA
  • ZIP: 98101
A ✓ Verified badge appears.
3

Manual Override (Optional)

If the user manually edits any field, the badge changes to ⚠ Unverified.This allows flexibility while clearly indicating validation status.

​
Required Smarty Products

Smarty sells different API products separately. For full functionality:
ProductWhat It DoesPrice
US Autocomplete ProType-ahead suggestions$21/month (5,000 lookups)
US Address VerificationUSPS validationFree tier: 250/month
Without Autocomplete Pro, the address field still works—users just type manually without suggestions. The verification badge will not appear.

​
Setup

​
1. Create a Smarty Account

  1. Go to smarty.com
  2. Sign up for an account
  3. Purchase US Autocomplete Pro subscription (if you want autocomplete)
  4. US Address Verification is included free

​
2. Get API Credentials

  1. Go to Dashboard → API Keys
  2. Copy your Auth ID and Auth Token
Use Secret Keys (Auth ID + Auth Token), not Embedded Keys. Secret keys are for server-side API calls.

​
3. Configure Environment Variables

Add to your .env.local: 
# Smarty Streets Address Verification
SMARTY_AUTH_ID=your-auth-id-here
SMARTY_AUTH_TOKEN=your-auth-token-here

​
4. Restart the Dev Server

npm run dev

​
Testing the Integration

Run the test script to verify your credentials: 
npx tsx scripts/test-smarty.ts
Expected output: 
🔍 Testing Smarty Streets API Connection...

✅ Street API (Verification) working!
   Verified: 1600 Pennsylvania Ave NW
   City: Washington
   State: DC

✅ Autocomplete API working!
   Found 5 suggestions:
   1. 1600 Pennsylvania Ave, Tyrone, PA 16686
   2. 1600 Pennsylvania Ave, Miami Beach, FL 33139

​
Using the Address Field

​
In the Form Builder

  1. Add an Address field from the field palette
  2. Configure options:
    • Include Unit: Add apartment/suite field
    • Required: Make the field mandatory

​
In Public Forms

The address field automatically:
  • Shows autocomplete when Smarty is configured
  • Falls back to manual entry when not configured
  • Displays verification status badges

​
Verification States

BadgeMeaning
✓ VerifiedUser selected from autocomplete suggestions
⚠ UnverifiedUser typed manually or edited after selection
(No badge)Address field is empty

​
Stored Data

The address field saves the following structure: 
{
  "address_field_id": {
    "street": "123 Main Street",
    "unit": "Apt 4B",
    "city": "Seattle",
    "state": "WA",
    "zip": "98101",
    "verified": true
  }
}
The verified flag lets admins filter submissions by address quality.

​
Architecture

​
Server Actions

Address operations use Next.js Server Actions for security: 
src/app/actions/smarty.ts
├── getAddressSuggestions()  # Autocomplete API
└── verifyAddress()          # Street API (available for future use)

​
Component

src/components/engine/fields/address-field.tsx
├── AutocompleteInput      # Type-ahead with Popover
├── State Selector         # Shadcn Select dropdown
└── Verification Badge     # Status indicator

​
Hydration Safety

The address field uses client-side mounting to prevent hydration mismatches with Radix UI: 
const [mounted, setMounted] = useState(false);

useEffect(() => {
  setMounted(true);
}, []);

if (!mounted) {
  return <SimplePlaceholder />;
}

return <RadixComponent />;
This ensures server-rendered HTML matches client-rendered HTML.

​
Common Issues

  1. Verify you have US Autocomplete Pro subscription (not just verification)
  2. Run npx tsx scripts/test-smarty.ts to check credentials
  3. Check browser console for errors
  4. Ensure you’re typing at least 3 characters
Your Smarty account needs an active US Autocomplete Pro subscription.US Address Verification (free tier) only validates complete addresses—it doesn’t provide autocomplete.
If you see React hydration warnings with the address field, ensure:
  1. The mounted state pattern is in place
  2. Radix UI components render only after mount
  3. SSR renders a placeholder, not the full Popover/Select
The test script uses direct HTTP calls. If autocomplete works in the script but not the app:
  1. Restart your dev server to pick up new env vars
  2. Check that .env.local is in the project root
  3. Verify the server action is being called (check Network tab)

​
Without Smarty Streets

Address fields work without Smarty configuration:
  • Users type addresses manually
  • No autocomplete suggestions
  • No verification badges
  • Data still saves correctly
This is useful for:
  • Development without API keys
  • Forms where verification isn’t critical
  • International addresses (Smarty is US-only)

Next: Adding Custom Fields

Learn how to extend the form engine with new field types.