# Address Normalization API

Use the Address Normalization API to standardize a US postal address into a consistent, component-based format. Submit an address in FullContact's standard location format and receive a canonical version with consistent casing, abbreviations, region names, region codes, and county.

Before integrating, review the [limitations](https://support.fullcontact.com/portal/en/kb/articles/fc-docs-address-normalization-api#limitations) below to confirm the service fits your use case.

* * *

## Endpoint

```
POST https://addressapi.service.fullcontact.com/v3/address.normalize
```

## Headers

```
Authorization: Bearer {Your API Key}
Content-Type: application/json
```

All requests require Bearer token authentication. Treat API keys as passwords — do not expose them in client-side code or public repositories.

* * *

## Request

The request body uses FullContact's standard location format, wrapped in an `address` object.

### Request Body

\| Parameter \| Type \| Required \| Description \|
\| \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \| \-\-\-\-\- \| \-\-\-\-\- \| \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\/\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\| `address` \| object \| Yes \| Wrapper for the address to be normalized. \|
\| `address.addressLine1` \| string \| Yes \| Primary street address line (e.g., `"1801 California St"`). \|
\| `address.addressLine2` \| string \| No \| Secondary line such as a suite, unit, or apartment (e.g., `"Suite 2400"`). \|
\| `address.city` \| string \| Conditional \| City name. Required when `postalCode` is not provided. \|
\| `address.region` \| string \| Conditional \| Full region/state name (e.g., `"Colorado"`). Either `region` or `regionCode` is required when `postalCode` is not provided. \|
\| `address.regionCode` \| string \| Conditional \| Region/state code (e.g., `"CO"`). Either `region` or `regionCode` is required when `postalCode` is not provided. \|
\| `address.postalCode` \| string \| Conditional \| Postal Code. Required when `city` and `region`/`regionCode` are not both provided. \|
\| `address.county` \| string \| No \| County name. Generally returned, not submitted. \|
\| `address.country` \| string \| No \| ISO country code (e.g., `"US"`). Defaults to `US` if omitted. \|

**Minimum required fields:**`addressLine1` plus **either**`postalCode` **or** both `city` and a region (`region` or `regionCode`). Requests that do not meet this threshold return a `400`.

### Example Request

```json
{
  "address": {
    "addressLine1": "1801 California St",
    "addressLine2": "Suite 2400",
    "city": "Denver",
    "region": "CO",
    "postalCode": "80202",
    "country": "US"
  }
}
```

* * *

## Response

### Response Body

\| Field \| Type \| Description \|
\| \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \| \-\-\-\-\-\- \| \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\n\| `address` \| object \| Wrapper for the normalized address. \|
\| `address.addressLine1` \| string \| Canonical street address. \|
\| `address.addressLine2` \| string \| null \| Canonical secondary line, or `null` if not present. \|
\| `address.city` \| string \| Canonical city name. \|
\| `address.region` \| string \| Full region/state name (e.g., `"Colorado"`). \|
\| `address.regionCode` \| string \| Region/state code (e.g., `"CO"`). \|
\| `address.postalCode` \| string \| Canonical postal code. \|
\| `address.county` \| string \| County for the normalized address. \|
\| `address.country` \| string \| ISO country code. \|

### Example Response (200 OK)

```json
{
  "address": {
    "addressLine1": "1801 California St",
    "addressLine2": "Suite 2400",
    "city": "Denver",
    "region": "Colorado",
    "regionCode": "CO",
    "postalCode": "80202",
    "county": "Denver",
    "country": "US"
  }
}
```

### Example Response (404 Not Found)

Returned when a normalized version of the submitted address could not be found.

```json
{
  "message": "Address not found in normalization cache"
}
```

### Example Response (400 Bad Request)

Returned when the request body is missing required fields or cannot be parsed.

```json
{
  "code": 400,
  "message": "Address must include a street address and either a postal code or a city and region."
}
```

* * *

## cURL Example

```bash
curl -X POST https://addressapi.service.fullcontact.com/v3/address.normalize \
  -H "Authorization: Bearer {Your API Key}" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "addressLine1": "1801 California St",
      "addressLine2": "Suite 2400",
      "city": "Denver",
      "region": "CO",
      "postalCode": "80202",
      "country": "US"
    }
  }'
```

* * *

## Response Codes

\| Code \| Meaning \|
\| \-\-\-\- \| \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\/\-\-\-\- \|
\| `200` \| Normalized address returned. \|
\| `400` \| Request body is missing required fields or could not be parsed. \|
\| `401` \| Authorization header is missing or the bearer token is invalid. \|
\| `404` \| A normalized version of the submitted address could not be found. \|
\| `422` \| The submitted address could not be processed after normalization cleanup. \|

* * *

## Normalization Examples

The examples below illustrate the kinds of variations the service can resolve. Each shows the JSON request body and the corresponding `200 OK` response.

### Street type spelled out, postal code omitted

The service abbreviates the street type (`Street` → `St`), expands the region (`CO` → `Colorado`), and fills in the postal code and county.

**Request**

```json
{
  "address": {
    "addressLine1": "1801 California Street",
    "city": "Denver",
    "region": "CO"
  }
}
```

**Response**

```json
{
  "address": {
    "addressLine1": "1801 California St",
    "addressLine2": null,
    "city": "Denver",
    "region": "Colorado",
    "regionCode": "CO",
    "postalCode": "80202",
    "county": "Denver",
    "country": "US"
  }
}
```

### Directional with punctuation

The service strips punctuation from directionals (`N.W.` → `NW`).

**Request**

```json
{
  "address": {
    "addressLine1": "1600 Pennsylvania Ave N.W.",
    "city": "Washington",
    "region": "DC"
  }
}
```

**Response**

```json
{
  "address": {
    "addressLine1": "1600 Pennsylvania Ave NW",
    "addressLine2": null,
    "city": "Washington",
    "region": "District of Columbia",
    "regionCode": "DC",
    "postalCode": "20500",
    "county": "District of Columbia",
    "country": "US"
  }
}
```

### Word-form street numbers and missing postal code

The service converts word-form street numbers to digits (`Fifth` → `5th`), abbreviates the street type, and fills in the postal code.

**Request**

```json
{
  "address": {
    "addressLine1": "350 Fifth Avenue",
    "city": "New York",
    "region": "NY"
  }
}
```

**Response**

```json
{
  "address": {
    "addressLine1": "350 5th Ave",
    "addressLine2": null,
    "city": "New York",
    "region": "New York",
    "regionCode": "NY",
    "postalCode": "10118",
    "county": "New York",
    "country": "US"
  }
}
```

### Postal code only — city and region inferred

When the request supplies only `addressLine1` and `postalCode`, the service infers `city`, `region`, `regionCode`, and `county`.

**Request**

```json
{
  "address": {
    "addressLine1": "1600 Pennsylvania Avenue NW",
    "postalCode": "20500"
  }
}
```

**Response**

* * *

## Limitations

- **Geographic Scope:** The service will **only process United States (US) addresses (Coverage in Puerto Rico is very limited)**.
- P.O. Boxes: Supported as a normal address.
- **Service Limitation:** This product **will not** perform address validation or verification.
- It **will not** confirm if an address is real, mailable, or deliverable.
- **Input Constraint:** The service will **not** accept single-string addresses (e.g., `"123 Main St, Anytown, CA 90210"`). Inputs must be broken into components.

## Notes

- **Region handling.** Either `region` (e.g., `"Colorado"`) or `regionCode` (e.g., `"CO"`) is accepted as input. Successful responses always include both.
- **Country default.** If `country` is omitted, the service treats the request as a US address.
- **Field naming.** The `address` object mirrors the location fields used elsewhere in the FullContact API (Enrich, Resolve), so payloads can be reused across endpoints.