# Verify Address

Validate and standardize a US shipping address against the address-service registry.
Only the United States and its territories (PR, GU, VI, MP, MH, AS) are accepted —
all other countries are rejected with HTTP 400.
**How to interpret a 200 response**
Use the `errored` and `corrected` together. Apply
the rules in the order below — the first matching branch wins.
1. **`errored == true` → Address is unusable**
Do **not** use the response fields as a shipping address. Prompt the user to
revise the input.
2. **`errored == false && corrected == true` → Address is non-standard**
The submitted address is not in its standard form — for example, the city name
is misspelled, the ZIP code is wrong or incomplete, or street abbreviations /
casing are off. The service was able to identify the intended address and
return a standardized version. **Strongly recommend the user update their
address before shipping.**
The response fields (`street`, `street2`, `city`, `state`, `zip`, `country`)
carry the **standardized address**. Surface them to the user (along with
`corrections[]` for context) and suggest adopting this version as the final
shipping address. See the example below — the user typed the misspelled
`Bsoton`, and the response returns the corrected `Boston`.
3. **`errored == false && corrected == false` → Fully valid**
The input matches the postal database exactly. Use it as-is — no confirmation needed.

**Decision tree (pseudocode)**

```
if (errored) {
  // Unusable — ask the user to revise
} else if (corrected) {
  // Usable — replace input with response fields,
  // optionally surface corrections[] for user confirmation
} else {
  // Fully valid — use as-is
}
```
**Additional fields**
- **`residential`** — whether the delivery point is residential. Defaults to `true` when the downstream service cannot determine it.
- **`corrections[].message`** / **`errors[].message`** — human-readable text
suitable for direct display to end users.

Endpoint: POST /api/addresses/verify
Version: v1
Security: BearerAuth, ApiTokenAuth

## Request fields (application/json):

  - `street` (string, required)
    Primary street address.
    Example: 123 Main St

  - `street2` (string)
    Secondary address line (apartment, suite, unit, etc.). Optional.
    Example: Apt 4B

  - `city` (string, required)
    City name.
    Example: San Francisco

  - `state` (string, required)
    Two-character state or territory code.
    Example: CA

  - `zip` (string, required)
    ZIP or postal code.
    Example: 94105

  - `country` (string, required)
    Country identifier. Only the United States and its territories are accepted. The value may be the ISO 3166-1 alpha-2 code (e.g., `US`, `PR`, `GU`, `VI`, `MP`, `MH`, `AS`) or a recognized country name (case-insensitive), such as `United States`, `USA`, `Puerto Rico`, `Guam`, `US Virgin Islands`, `Northern Mariana Islands`, `Marshall Islands`, or `American Samoa`. Other values are rejected with HTTP 400.
    Example: US

## Response 200 fields (application/json):

  - `street` (string)
    Standardized primary street address (or echo of input when not matched).
    Example: 1 MAIN ST

  - `street2` (string)
    Standardized secondary address line (or echo of input when not matched).
    Example: STE 100

  - `city` (string)
    Standardized city name (or echo of input when not matched).
    Example: ANYTOWN

  - `state` (string)
    Standardized state or territory code.
    Example: CA

  - `zip` (string)
    Standardized ZIP or postal code, typically expanded to ZIP+4 when matched.
    Example: 90001-1234

  - `country` (string)
    Country code.
    Example: US

  - `residential` (boolean)
    Whether the address is residential. Defaults to `true` when residential status cannot be determined.
    Example: false

  - `errored` (boolean)
    `true` when the address is unusable — either not found, or matched but requiring additional information (e.g., apartment/suite number). See `errors[]` for details.
    Example: false

  - `corrected` (boolean)
    `true` when one or more fields were modified during standardization (e.g., corrected street spelling or ZIP code). See `corrections[]` for details.
    Example: false

  - `standardized` (boolean)
    Example: true

  - `corrections` (array)
    Field-level corrections applied during standardization. Empty when no corrections were made.
    Example: [{"message":"Corrected ZIP Code"}]

  - `corrections.message` (string)
    Human-readable message describing a correction or error.
    Example: Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address.

  - `errors` (array)
    Validation errors reported during address verification. Empty when the address is usable.
    Example: []

## Response 400 fields (application/json):

  - `message` (string)
    Human-readable error message.
    Example: Invalid request parameters.