Address Search

Verify Address

Verifies an address against the USPS Coding Accuracy Support System (CASS) and returns it standardized and corrected.

Submit the whole address in query, or the first address line in query with either zip_code, or city and state. A freeform query is parsed into those components before the search runs.

A match returns the standardized address lines, city, state and ZIP+4, scored by fit and confidence. It also carries the CASS record behind the match: delivery point, DPV flags, carrier route, eLOT, county, congressional district, RDI, time zone and coordinates. No match returns 200 with a count of 0, a null match and empty address fields.

Only a match draws on your balance. A key without address verification enabled returns 401. A verification still running after 9.5 seconds aborts with 429.

Countries

Verify defaults to the United States, where it is CASS certified. Pass context with an ISO 3166-1 alpha-3 country code to verify an address elsewhere, e.g. context=GBR or context=FRA. The address datasets your key is licensed for decide which countries it can verify.

Outside the United States there is no CASS record to return, so match carries the standardized address from that country's dataset instead. The top-level fields (address_line_one, city, state, zip_code, country_iso_2) are populated for every country, along with confidence and fit.

post/verify/addresses

Request

  • Base URL: https://api.addresszen.com/v1
  • URL: https://api.addresszen.com/v1/verify/addresses
  • Auth: HTTP bearer

Query parameters

api_keystring

API Key

Your unique identifier that allows access to our APIs.

Begins ak_. Available from your dashboard.

tagsstring

Tags

A comma separated list of tags to query over.

Useful if you want to specify the circumstances in which the request was made.

If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar".

contextstring

Identify the country of the address to verify. Defaults to United States (USA)

Request body

querystring required

Address input to verify.

If submitting a freeform address verification query, enter the full address. E.g. query=123 Main St, Springfield, CO, 81073

Otherwise, query can be accompanied with the following address components:

  • zip_code
  • city and state

If you supply zip_code, or city and state, omit that information from query and use it for the first address line only. E.g. query=123 Main St

zip_codestring

Specify the ZIP code of an address. The following formats are accepted: 81073-1119, 810731119, 81073.

citystring

City of an address.

statestring

State of an address. For the US, use the 2 letter state abbreviation.

Example request

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

Response

Success

code2000 required
message'Success' required

Example response

{
  "result": {
    "match": {
      "address1": "1010 Cauthen Ln",
      "address2": "",
      "address3": "",
      "area_code": "575",
      "carrier_route": "C019",
      "check_digit": "4",
      "city": "Alamogordo",
      "city_abbreviation": "",
      "congressional_district": "02",
      "country_code": "US",
      "county": "Otero",
      "day_light_savings": true,
      "delivery_point": "10",
      "dpv": "Y",
      "dpv_cmra": "N",
      "dpv_footnotes": "AABB",
      "dpv_no_stat": "N",
      "dpv_vacant": "N",
      "elot": "0133A",
      "finance_number": "340105",
      "fips_county_code": "035",
      "firm": "",
      "footnotes": "M0>",
      "geo_coded": true,
      "lacs_indicator": "",
      "lacs_link_footnote": "",
      "lacs_link_indicator": "",
      "latitude": "32.91278",
      "longitude": "-105.94904",
      "parsed_pmb_designator": "",
      "parsed_pmb_number": "",
      "parsed_post_directional": "",
      "parsed_pre_directional": "",
      "parsed_primary_number": "1010",
      "parsed_street_name": "Cauthen",
      "parsed_suffix": "Ln",
      "parsed_unit_designator": "",
      "parsed_unit_number": "",
      "rdi": "Y",
      "record_type": "S",
      "state": "NM",
      "suite_link_footnote": "",
      "time_zone": "MST",
      "urbanization": "",
      "zip_code": "88310-5631"
    },
    "match_information": "Single Response - The delivery address was found in the National Database and no further information was required.",
    "address_line_one": "123 Main St",
    "city": "Springfield",
    "state": "CO",
    "zip_code": "81073-1119",
    "country_iso_2": "US"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.