Get Address Suggestions

​

Description

​

Input

• Query Parameter: address (string, required) — Partial or full address text to search. Minimum 3 characters recommended. URL-encoded.
  • Examples: “123 Main”, “123 Main St New York”, “10001”

​

Output

• success (bool) — Always true for successful API calls
• code (int) — Result code (always 200)
• errorMessage (string) — Null on success
• entries (array) — List of validated address suggestions, or empty array if no matches
  • street_line — Primary street address
  • secondary — Apartment/suite number (empty if single-unit)
  • city — Standardized city name
  • state — Two-letter state abbreviation
  • zipcode — Five-digit ZIP code
  • entries — Number of units at this address (1=single unit, >1=multi-unit building)

​

Example Request (Partial Address)

GET /api/admin/addresses/lookup?address=123%20Main%20St%20New%20York
Authorization: Bearer {token}

​

Example Response (Single Family Home)

{
  "success": true,
  "code": 200,
  "errorMessage": null,
  "entries": [
    {
      "street_line": "123 Main St",
      "secondary": "",
      "city": "New York",
      "state": "NY",
      "zipcode": "10001",
      "entries": 1
    }
  ]
}

​

Example Response (Multi-Unit Building)

{
  "success": true,
  "code": 200,
  "errorMessage": null,
  "entries": [
    {
      "street_line": "456 Park Ave",
      "secondary": "",
      "city": "New York",
      "state": "NY",
      "zipcode": "10022",
      "entries": 50
    },
    {
      "street_line": "456 Park Ave",
      "secondary": "Apt 1A",
      "city": "New York",
      "state": "NY",
      "zipcode": "10022",
      "entries": 1
    }
  ]
}

​

Example Response (No Results)

{
  "success": true,
  "code": 200,
  "errorMessage": null,
  "entries": []
}

​

Errors

• 200 OK — Always returned; check the success property in the response body.
• 401 Unauthorized — Missing or invalid authentication token. Ensure JWT token is valid and includes AdminUI scope.
• Empty Results (Not an Error) — No matching addresses found. Frontend should allow manual address entry or prompt user to refine search.
• Missing Parameter — Query parameter ‘address’ is required. Returns empty results if missing.
• SmartyStreets API Failure — External service unavailable. Returns empty results to avoid blocking user.
• Configuration Error — Missing or invalid SmartyStreets credentials in appsettings.json.
• Rate Limit Exceeded — SmartyStreets API quota exhausted. Returns empty results until quota resets (typically monthly).

​

Understanding Empty Results

• The address doesn’t match any known US addresses in the USPS database
• Search text is too short or generic (e.g., “Main”) without city/state context
• Misspelled street name or city doesn’t match fuzzy matching threshold
• User entered an international address (only US addresses supported)
• SmartyStreets API is down or unreachable (graceful degradation)
• Very recently constructed addresses may not yet be in USPS database
• Some rural addresses use non-standard formats requiring different API endpoint

​

Notes

• Authentication Required: Admin-level access with valid JWT token.
• US Addresses Only: Only US addresses are supported via SmartyStreets US Street API.
• Performance: Results typically returned in 50-150ms depending on API response time.
• Graceful Degradation: Service failures return empty results rather than throwing errors to avoid blocking UX.
• URL Encoding: Address parameter should be URL-encoded (spaces as %20).
• Multi-Unit Buildings: When entries > 1, prompt user to specify apartment/suite number.
• Caching: Consider implementing client-side caching for repeated searches to improve performance and reduce costs.

​

Frontend Integration Best Practices

• Debouncing: Implement 250-500ms debounce on keyup events to reduce API calls as user types.
• Minimum Length: Only trigger lookup when user has typed at least 3 characters.
• Loading State: Show loading indicator while request is in flight.
• Empty State: Display helpful message when no results returned (e.g., “No addresses found. Try adding city or ZIP code.”).
• Manual Entry Fallback: Always provide option to manually enter address if autocomplete doesn’t find it.
• Error Handling: Handle 401 errors by redirecting to login; handle timeouts gracefully.
• Multi-Unit Handling: When entries > 1, show “Multiple units available” and prompt for apt/suite number.
• Form Population: Parse selected suggestion into separate form fields (street, city, state, ZIP) rather than single field.

​

Related Operations

• After address selection, use CompanyController.CreateEntry or UpdateEntry to save address to company record.
• Use validated addresses when creating billing profiles via ProjectPaymentProcessorController.
• Address data may be used for fraud detection and transaction risk scoring.

[]