Address Normalization API

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

{
  "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)

{
  "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.

{
  "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.

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

cURL Example

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

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

Response

{
  "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

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

Response

{
  "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

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

Response

{
  "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

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

Response

{
  "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.