latestOpenAPI 3.1.02026-08-194237902.5 MB

563848e0ecc0

AddressStandardization

Standardize and validate a postal address

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.

post/addresses/standardize

Headers

tenant-idstring required

Request body

addressLine1string required

Primary street line

addressLine2string

Secondary street line (apt, suite, unit, floor)

citystring

City

countystring

County

statestring

State / province code

zipstring

ZIP / postal code (5 or 5+4, hyphen-separated)

countrystring

ISO country code

addressTypestring

Optional address type hint (e.g. billing, mailing, office, remit_to, service, irs)

Example request

{
  "addressLine1": "123 Main Street",
  "addressLine2": "Suite 100",
  "city": "New York",
  "county": "New York County",
  "state": "NY",
  "zip": "10001",
  "country": "US",
  "addressType": "billing"
}

Response

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.

confidence'HIGH' | 'MEDIUM' | 'LOW'

validationStatus'VALID' | 'PARTIAL' | 'INVALID'

Example response

{
  "enrichment": {
    "zip4": "1234",
    "county": "New York County",
    "stateFips": "36",
    "countyFips": "36061"
  }
}