Skip to main content

Address Verification

Clean, standardize, and validate US addresses using USPS CASS-certified data.

Address Verification (also known as address cleansing) takes a complete address and validates it against authoritative postal data, returning a standardized, deliverable address or an error if the address cannot be verified.

When to Use Address Verification​

  • Data Quality: Clean existing address databases or spreadsheets
  • Form Validation: Verify addresses after form submission
  • Order Processing: Validate shipping addresses before fulfillment
  • CRM Integration: Ensure accurate customer addresses

API Endpoint​

POST https://api.addresszen.com/v1/verify/addresses

Authentication​

Include your API key as a query parameter:

?api_key=ak_test

Request Format​

The API accepts addresses in three flexible formats:

Option 1: Full Address String​

Submit the complete address as a single string:

{
  "query": "123 Main St, Springfield, CO 81073-1119"
}

Option 2: Address with ZIP Code​

Separate the street address from the ZIP code:

{
  "query": "123 Main St, Springfield CO",
  "zip_code": "81073-1119"
}

Option 3: Address with City and State​

Provide structured address components:

{
  "query": "123 Main St",
  "city": "Springfield",
  "state": "CO"
}

Example Implementation​

cURL​

curl -X POST "https://api.addresszen.com/v1/verify/addresses?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "123 Main St, Springfield, CO 81073"
  }'

JavaScript (Fetch)​

const verifyAddress = async (address) => {
  const response = await fetch(
    "https://api.addresszen.com/v1/verify/addresses?api_key=YOUR_API_KEY",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        query: address,
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
};

// Usage
verifyAddress("123 Main St, Springfield, CO 81073")
  .then((result) => console.log(result))
  .catch((error) => console.error("Verification failed:", error));

Python​

import requests

def verify_address(address):
    url = "https://api.addresszen.com/v1/verify/addresses"
    params = {
        "api_key": "YOUR_API_KEY"
    }
    headers = {
        "Content-Type": "application/json"
    }
    data = {
        "query": address
    }

    response = requests.post(url, json=data, headers=headers, params=params)
    response.raise_for_status()

    return response.json()

# Usage
result = verify_address("123 Main St, Springfield, CO 81073")
print(result)

Node.js (Axios)​

const axios = require("axios");

const verifyAddress = async (address) => {
  try {
    const response = await axios.post(
      "https://api.addresszen.com/v1/verify/addresses?api_key=YOUR_API_KEY",
      { query: address },
      {
        headers: {
          "Content-Type": "application/json",
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Verification error:", error.response?.data || error.message);
    throw error;
  }
};

// Usage
verifyAddress("123 Main St, Springfield, CO 81073").then((result) =>
  console.log(result),
);

Response Format​

A successful verification returns the standardized address components:

{
  "result": {
    "query": "8 Morgan Ave Cullman, AL, 35058-0138",
    "query_state": "",
    "query_city": "",
    "query_zip_code": "",
    "count": 1,
    "address_line_one": "8 Morgan Ave",
    "address_line_two": "",
    "city": "Cullman",
    "state": "AL",
    "zip_code": "35058",
    "country_iso_2": "US",
    "match_information": "Single Response - The delivery address was found in the National Database and no further information was required.",
    "confidence": 1,
    "fit": 1,
    "match": {
      "address1": "8 Morgan Ave",
      "address2": "",
      "address3": "",
      "area_code": "256",
      "carrier_route": "R015",
      "check_digit": "9",
      "city": "Cullman",
      "city_abbreviation": "",
      "congressional_district": "04",
      "country_code": "US",
      "county": "Cullman",
      "day_light_savings": true,
      "delivery_point": "",
      "dpv": "N",
      "dpv_cmra": "",
      "dpv_footnotes": "AAM3",
      "dpv_no_stat": "",
      "dpv_vacant": "",
      "elot": "",
      "finance_number": "012220",
      "fips_county_code": "043",
      "firm": "",
      "footnotes": "0<",
      "geo_coded": true,
      "lacs_indicator": "",
      "lacs_link_footnote": "",
      "lacs_link_indicator": "",
      "latitude": "34.23",
      "longitude": "-86.74375",
      "parsed_pmb_designator": "",
      "parsed_pmb_number": "",
      "parsed_post_directional": "",
      "parsed_pre_directional": "",
      "parsed_primary_number": "8",
      "parsed_street_name": "Morgan",
      "parsed_suffix": "Ave",
      "parsed_unit_designator": "",
      "parsed_unit_number": "",
      "rdi": "",
      "record_type": "S",
      "state": "AL",
      "suite_link_footnote": "",
      "time_zone": "CST",
      "urbanization": "",
      "zip_code": "35058"
    }
  },
  "code": 2000,
  "message": "Success"
}

Error Handling​

The API returns appropriate HTTP status codes:

  • 200 OK: Address successfully verified
  • 400 Bad Request: Invalid request format or parameters
  • 401 Unauthorized: Invalid or missing API key
  • 429 Too Many Requests: Rate limit exceeded

Best Practices​

  1. Batch Processing: For multiple addresses, consider implementing queue-based processing with appropriate rate limiting
  2. Error Handling: Always handle cases where addresses cannot be verified
  3. Caching: Cache verified addresses to reduce API calls for repeated verifications
  4. Input Sanitization: Clean input data before submission (remove extra spaces, standardize abbreviations)

Rate Limits​

Please refer to your account dashboard for current rate limits. Contact support if you need higher limits for bulk processing.

Next Steps​