# United States (US)

US addresses require a state (`administrativeArea`) in addition to the standard
fields. The house number comes before the street name, and postal codes (ZIP
codes) are 5 digits with an optional 4-digit extension.

## Example


```json
{
  "countryCode": "US",
  "postalCode": "94105",
  "addressLines": ["123 Market Street", "Suite 400"],
  "locality": "San Francisco",
  "administrativeArea": "CA"
}
```

## Field requirements

| Field | Required | Description |
|  --- | --- | --- |
| `countryCode` | Yes | Always `"US"` |
| `postalCode` | Yes | 5-digit ZIP code (optionally with +4 extension) |
| `addressLines` | Yes (for shipment) | Index 0: number, street name, and type |
| `locality` | Yes (for shipment) | City |
| `administrativeArea` | **Yes** | 2-letter state abbreviation (e.g., `"CA"`, `"NY"`, `"TX"`) |
| `subLocality` | No | Neighborhood — rarely needed |


## Postal code

- **Format:** 5 digits, optionally followed by a dash and 4 more digits
- **Regex:** `^\d{5}(-\d{4})?$`
- **Examples:** `"94105"`, `"94105-1234"`
- **Sanitization:** The API strips all characters except digits and dashes


The 4-digit ZIP+4 extension improves delivery precision but is not required.
Most checkouts collect only the 5-digit ZIP code.

## Administrative area (state)

The `administrativeArea` field is **required** for the United States. It must be
a valid 2-letter USPS state abbreviation.

All 50 states, the District of Columbia, and US territories are supported:

- **States:** `AL`, `AK`, `AZ`, `AR`, `CA`, `CO`, `CT`, `DE`, `FL`, `GA`,
`HI`, `ID`, `IL`, `IN`, `IA`, `KS`, `KY`, `LA`, `ME`, `MD`, `MA`, `MI`,
`MN`, `MS`, `MO`, `MT`, `NE`, `NV`, `NH`, `NJ`, `NM`, `NY`, `NC`, `ND`,
`OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VA`,
`WA`, `WV`, `WI`, `WY`
- **Federal district:** `DC`
- **Territories:** `AS`, `GU`, `MH`, `FM`, `MP`, `PW`, `PR`, `VI`
- **Military:** `AA`, `AE`, `AP`


The [address form endpoint](/developer-resources/ingrid-api/guides/address-form) returns `administrativeArea` as
a `select` field type with all valid options pre-populated.

## Address lines

The house number comes **before** the street name, followed by the street type.

| Scenario | `addressLines` value |
|  --- | --- |
| Standard | `["123 Market Street"]` |
| With suite | `["123 Market Street", "Suite 400"]` |
| With apartment | `["456 Oak Avenue", "Apt 2B"]` |
| PO Box | `["PO Box 1234"]` |


- Apartment, suite, unit, and floor numbers go on the second address line
- Street types (Street, Avenue, Boulevard, etc.) are part of the first line


## Locality

The `locality` field is the **city**.

- **Example:** `"San Francisco"`, `"New York"`, `"Austin"`
- The city can be pre-filled from the ZIP code using the
[address form endpoint](/developer-resources/ingrid-api/guides/address-form)


## Common mistakes

| Mistake | Problem | Fix |
|  --- | --- | --- |
| Missing `administrativeArea` | Required for US addresses | Include the 2-letter state code |
| `"administrativeArea": "California"` | Full state name instead of abbreviation | Use the abbreviation: `"CA"` |
| `"addressLines": ["Market Street 123"]` | Street before number | US uses number-first: `["123 Market Street"]` |
| `"postalCode": "94,105"` | Comma in ZIP code | The API strips non-digit characters automatically |