Address Normalization API

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

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

Example Response (400 Bad Request)

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

Street type spelled out, postal code omitted

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

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

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

Request

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

Response

Limitations

Notes