---
updatedAt: 2026-05-20T17:25:11.000Z
agentTools:
  projectIndex: https://docs.fullcontact.com/llms.txt
---

# 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](#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                                         |
| ---------------------- | -------------- | --------------------------------------------------- |
| `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**

```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"
  }
}
```

***

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