Standardize and validate a postal address
POST/addresses/standardize
What: Validates and standardizes a postal address, returning a confidence tier (HIGH / MEDIUM / LOW), a validation status (VALID / PARTIAL / INVALID), and enrichment data (ZIP+4, county, latitude/longitude). Does not persist any data — this is a read-only preview operation.
When: Call this before persisting an address to give users a corrected form they can confirm or override. This is not the persistence write path; saving the address to a provider or facility record requires a separate write call. Applies to all address types (billing, mailing, office, etc.).
How: Authentication is required (valid JWT). The calling tenant must have address standardization enabled in their configuration; requests from tenants without this feature return 403. Supply the tenant-id header and a request body containing at least addressLine1. Omitting country or passing blank defaults it to "US", and "USA" is normalized to "US". The addressType field is an optional free-form hint (values such as billing, mailing, office, remit_to, service, irs).
Returns: A single object with four blocks: standardizedAddress (the cleansed address fields, for display), confidence (the reliability tier), validationStatus (provider validation outcome), and enrichment (ZIP+4, county, coordinates, FIPS codes). Use enrichment — not standardizedAddress — as the authoritative block when persisting. Confidence guidance: HIGH = safe to auto-apply; MEDIUM = present as a suggestion for user review; LOW = warn the user and require manual confirmation. enrichment.timezone is always null in the current release. This endpoint is idempotent — repeated calls with the same input produce the same output and have no side effects.
Request
Responses
- 200
- 204
- 400
- 401
- 403
- 500
- 502
The standardization result. standardizedAddress holds the corrected address fields for display; confidence is the HIGH/MEDIUM/LOW reliability tier; validationStatus is the provider outcome (VALID/PARTIAL/INVALID); enrichment holds ZIP+4, county, latitude, longitude and FIPS codes. Use enrichment — not standardizedAddress — as the authoritative block when saving the address. Interpret confidence to drive UX: HIGH = auto-apply, MEDIUM = suggest for review, LOW = warn and require explicit confirmation. enrichment.timezone is always null in the current release.
No standardization result was available — the standardizer may be disabled; treat as unavailable and fall back to unvalidated address entry.
The request could not be processed due to invalid input. Two body shapes are possible depending on the cause: (1) bean-validation failures on the request body (addressLine1 is blank or missing, or zip does not match the required 5 or 5+4 digit format) and a missing/blank tenant-id header both return the nested shape {"errors": [{"httpStatus", "title", "reason", "detail"}]} — for the missing-header case title is "Missing Headers" and reason/detail are "tenant-id header missing."; (2) a 400 passed through from the upstream DAL standardizer instead uses the flat shape {"title", "detail"}. Fix the indicated field or header and retry.
The request was not authenticated. Obtain a valid JWT and include it in the Authorization header before retrying.
Access denied. A missing tenant-id header does not return this status — see the 400 response above. Returned instead when: (1) the identified tenant does not have address standardization enabled in their configuration, returning the flat shape {"title": "Forbidden", "detail": "Address standardization is not enabled for this tenant."}; or (2) the upstream DAL standardizer itself returns 403 for this request, passed through with the same flat {"title", "detail"} shape.
An unexpected server-side error occurred, such as the upstream standardization service not responding within the configured timeout (default 30 seconds) or an internal processing error. Retry with exponential backoff; if the error persists, contact support.
The upstream address standardization service was unreachable or returned a server-side error. This is a transient condition — retry the request with exponential backoff.