---
title: "Standardize and validate a postal address"
method: POST
path: "/addresses/standardize"
tags: ["AddressStandardization"]
---

# 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.

## Headers

- `tenant-id` string, required

## Request body

- StandardizeAddressRequest — Input address to be standardized and validated
  - `addressLine1` string, required — Primary street line
  - `addressLine2` string — Secondary street line (apt, suite, unit, floor)
  - `city` string — City
  - `county` string — County
  - `state` string — State / province code
  - `zip` string — ZIP / postal code (5 or 5+4, hyphen-separated)
  - `country` string — ISO country code
  - `addressType` string — Optional address type hint (e.g. billing, mailing, office, remit_to, service, irs)

## Response `200`

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.

- StandardizeAddressResponse — Standardized address with confidence, validation status, and enrichment data
  - `standardizedAddress` StandardizedAddress — Standardized address components
    - `addressLine1` string — Standardized primary street line
    - `addressLine2` string — Standardized secondary street line
    - `city` string — Standardized city
    - `county` string — Standardized county
    - `state` string — Standardized state code
    - `zip` string — Standardized ZIP / postal code
    - `zip4` string — ZIP+4 extension, if available
    - `country` string — Country code
    - `formattedAddress` string — Pretty-printed single-line address
  - `confidence` 'HIGH' | 'MEDIUM' | 'LOW'
  - `validationStatus` 'VALID' | 'PARTIAL' | 'INVALID'
  - `enrichment` AddressEnrichment — Enrichment values attached to the standardized address
    - `zip4` string — ZIP+4 extension, if available
    - `county` string — County name, if available
    - `latitude` number, double — Latitude in decimal degrees, if available
    - `longitude` number, double — Longitude in decimal degrees, if available
    - `stateFips` string — 2-digit state FIPS code, if available
    - `countyFips` string — 5-digit county FIPS code, if available
    - `formattedAddress` string — Pretty-printed single-line address, if available
    - `timezone` string, nullable — IANA timezone ID, if available; always null until timezone enrichment ships

## Other responses

- `204` — No standardization result was available — the standardizer may be disabled; treat as unavailable and fall back to unvalidated address entry.
- `400` — 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.
- `401` — The request was not authenticated. Obtain a valid JWT and include it in the Authorization header before retrying.
- `403` — 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.
- `500` — 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.
- `502` — The upstream address standardization service was unreachable or returned a server-side error. This is a transient condition — retry the request with exponential backoff.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)