Skip to main content

Address Verification

Clean, standardize and validate addresses in the US, where verification is CASS certified, and in every other country on your plan.

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

Countries​

Verify defaults to the United States. To verify an address elsewhere, add context with the country's ISO 3166-1 alpha-3 code, the Context column on supported countries. The address datasets your key is licensed for decide which countries it can verify.

Send the whole address in query, typed the way the customer typed it. Verify handles abbreviations, missing accents and local postal code formats per country.

curl -X POST "https://api.addresszen.com/v1/verify/addresses?api_key=YOUR_API_KEY&context=NLD" \
  -H "Content-Type: application/json" \
  -d '{ "query": "1012LG 1" }'

Outside the United States there is no CASS record. match is the address in the format Retrieve Address returns, with dataset naming the source. native holds that dataset's record untouched. The top-level fields, confidence and fit are the same in every country. Trimmed response:

{
  "result": {
    "query": "1012LG 1",
    "count": 1,
    "address_line_one": "Damrak 1",
    "address_line_two": "",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "zip_code": "1012 LG",
    "country_iso_2": "NL",
    "confidence": 0.6,
    "fit": 1,
    "match": {
      "dataset": "kadaster",
      "country_iso": "NLD",
      "line_1": "Damrak 1",
      "street_name": "Damrak",
      "primary_number": "1",
      "city": "Amsterdam",
      "native": {
        "openbare_ruimte_naam": "Damrak",
        "nummeraanduidingen_huisnummer": "1",
        "nummeraanduidingen_postcode": "1012 LG",
        "woonplaats_naam": "Amsterdam",
        "latitude": 52.377094097142596,
        "longitude": 4.897978171923001
      }
    }
  },
  "code": 2000,
  "message": "Success"
}

Check dataset to tell the two shapes apart. It is present on every non-US match and absent from a CASS match.

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 US verification returns the standardized address components and the CASS record:

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