Verify Address

POST/v1/verify/addresses

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.

Query parameters

api_key string optional: API Key

Your unique identifier that allows access to our APIs.

Begins ak_. Available from your dashboard.
Example ak_test
tags string optional: 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".
Example foo,bar
context string optional: Identify the country of the address to verify. Defaults to United States (USA)
Example usa

Request body

A JSON object holding the address to verify. Only query is required.

body object
- query string 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
  Example
  123 Main St, Springfield, CO 81073
- zip_code string optional
  Specify the ZIP code of an address. The following formats are accepted: 81073-1119, 810731119, 81073.
  Example
  81073-1119
- city string optional
  City of an address.
  Example
  Springfield
- state string optional
  State of an address. For the US, use the 2 letter state abbreviation.
  Example
  CO

Response

result is one of two shapes: a verified match with the standardized address fields and deliverability indicators, or a no-match object. The response sits inside the standard { result, code, message } envelope; see the API reference for the wrapper format.

result one of
- UsaVerifyMatch
  - query string
    Submitted query
  - query_city string
    Submitted city
  - query_state string
    Submitted state
  - query_zip_code string
    Submitted zip_code
  - match object
    Nearest matching address
    address1 string
    Primary delivery address
    address2 string
    Secondary address information
    address3 string
    Additional secondary address information
    area_code string
    Area code. Also known as Numbering Plan Area (NPA) https://en.wikipedia.org/wiki/List_of_North_American_Numbering_Plan_area_codes
    carrier_route string
    Data required to perform a Carrier Route sort
    check_digit string
    Character following the 5 or 9 digit ZIP Code. Part of the 11-digit barcode
    city string
    City name
    city_abbreviation string
    City Abbreviation. Empty string if not present
    congressional_district string
    Identifies the Congressional District. Empty string if not present
    country_code string
    ISO3166 country code. Empty string if not present
    county string
    Name of the county
    day_light_savings boolean
    Daylight saving time indicator
    delivery_point string
    Last 2 digits of the primary street address number or Post Office box
    dpv string
    Delivery Point Validation (DPV) Confirmation code.
    
    Possible values:
    
    'Y' Primary and secondary address information was validated
    
    'S' Extraneous or incorrect secondary address present
    
    'D' Secondary address information missing
    
    'N' Primary and secondary address information was not validated
    
    '' Address was not submitted to DPV lookup. Address was not ZIP+4 matched.
    
    Values
    "Y"
    "S"
    "D"
    "N"
    ""
    dpv_cmra string
    Delivery Point Validation (DPV) CMRA code.
    
    Indicates if the address is linked to a Commercial Mail Receiving Agency (CMRA), such as the UPS Store or Mailboxes Etc., where USPS mail can be sent or received.
    
    Possible values:
    
    'Y' Address is associated with a CMRA
    
    'N' Address is not associated with a CMRA
    
    '' Empty string if address is not DPV validated.
    
    Values
    "Y"
    "N"
    ""
    dpv_footnotes string
    Delivery Point Validation (DPV) Footnotes. Empty string if not present
    
    Possible values:
    
    'AA' ZIP+4 matched.
    
    'A1' ZIP+4 did not match.
    
    'BB' Primary and secondary address information was DPV validated.
    
    'CC' Primary address information was DPV validated. Input secondary address information dropped.
    
    'F1' Military address.
    
    'G1' General delivery address.
    
    'N1' Primary address information was DPV validated. Highrise address with missing secondary address information.
    
    'M1' Primary number missing from address.
    
    'M3' Primary number invalid.
    
    'P1' Box number missing.
    
    'P3' Box number invalid.
    
    'RR' Validated CMRA address with PMB information.
    
    'R1' Validated CMRA address without PMB information.
    
    'U1' Unique 5-digit ZIP code.
    
    dpv_no_stat string
    Delivery Point Validation (DPV) NoStat code.
    
    Indicates whether the address is a vacant property, it receives mail as a part of a drop, or it does not have an established delivery yet.
    
    Possible values:
    
    'Y' Confirmed
    
    'N' Not confirmed
    
    '' Empty string if address is not DPV validated.
    
    Values
    "Y"
    "N"
    ""
    dpv_vacant string
    Delivery Point Validation (DPV) Vacant code.
    
    USPS records indicate that although this may be a valid address, the residence or business is vacant.
    
    Possible values:
    
    'Y' Confirmed vacant
    
    'N' Not confirmed vacant
    
    '' Empty string if address is not DPV validated.
    
    Values
    "Y"
    "N"
    ""
    elot string
    Enhanced Line of Travel. For arranging records in the order that a route is served by a carrier. eLOT sequencing, when combined with Carrier Route codes, may allow Enhanced Carrier Route (ECR) discounts to be claimed.
    finance_number string
    Internal accounting number used by the USPS® when Post Offices or ZIP Codes are discontinued and reassigned. The finance number reflects the geographic grouping of ZIP + 4 areas in which these changes can be made.
    
    Empty string if not present
    fips_county_code string
    Federal Information Processing Standard code for a county. Empty string if not present
    firm string
    Company name in a business address
    footnotes string
    Letter codes returned by ZIP+4 encoding. Empty string if not present
    geo_coded boolean
    Indicates whether the address was geo-coded
    lacs_indicator string
    Indicates whether a record may benefit from LACS processing.
    
    Possible values:
    
    'L' Yes
    
    '' No
    
    Values
    "L"
    ""
    lacs_link_footnote string
    LACSLink Footnote. Return Code returned by the LACSLink process when an accurate address match could not be made. These codes help identify the type of move and the type of deficiency in the record which prevents a match. Possible values:
    
    'A' Address matched
    
    '00' No match
    
    '09' The input record matched to a record in the master file, but the old address is a highrise default
    
    '14' The input record matched to a record in the master file. The new address could not be converted to a deliverable address
    
    '92' LACSLink Record: Secondary Number Dropped from Input Address - The input record matched to a master file record, but the input address had a secondary number and the master file record did not. The record is a ZIP + 4 street level or high-rise match
    
    '' Address not submitted to LACSLink lookup
    
    Values
    "A"
    "00"
    "09"
    "14"
    "92"
    ""
    lacs_link_indicator string
    LACSLink Indicator. Indicates whether the input address matched a record in the LACSLink database.
    
    Possible values:
    
    'Y' Matched a record in the master file
    
    'S' The input record matched a master file record, but the input address included a secondary number that the master file record lacked
    
    'N' No match
    
    '' Empty string if not present
    
    Values
    "Y"
    "S"
    "N"
    ""
    latitude string
    Latitude of the encoded address. Empty string if not present
    longitude string
    Longitude of the encoded address. Empty string if not present
    parsed_pmb_designator string
    Information if a Private Mail Box (PMB) is found in an address. Empty string if not present
    parsed_pmb_number string
    Information if a Private Mail Box (PMB) is found in an address. Empty string if not present
    parsed_post_directional string
    Notation following the street name indicating street direction. Empty string if not present
    parsed_pre_directional string
    Notation preceding the street name indicating street direction. Empty string if not present
    parsed_primary_number string
    Number preceding the street name. Empty string if not present
    parsed_street_name string
    Street name. Empty string if not present
    parsed_suffix string
    Part of the delivery address line following the street name. Empty string if not present
    parsed_unit_designator string
    Identification of the secondary address unit. Empty string if not present
    parsed_unit_number string
    Apartment or suite number. Empty string if not present
    rdi string
    Residential Delivery Indicator (RDI). Indicates whether USPS classifies the delivery point as residential. Empty string if not present
    record_type string
    Type of address record.
    
    Possible values:
    
    'C' Multi-Carrier
    
    'F' Firm
    
    'G' General Delivery
    
    'H' High-rise or Apartment Building
    
    'M' Military
    
    'P' PO Box
    
    'R' Route (Rural Route/Highway Contract)
    
    'S' Street
    
    'U' Unique 5-Digit
    
    Values
    "C"
    "F"
    "G"
    "H"
    "M"
    "P"
    "R"
    "S"
    "U"
    ""
    state string
    Standard two-letter state abbreviation
    suite_link_footnote string
    Results of the SuiteLink lookup.
    
    Possible values: ' ' (Space), '00' (Double Zero), 'A' (A). Empty string if not present
    Values
    ""
    "00"
    "A"
    time_zone string
    Time zone. Empty string if not present
    urbanization string
    Urban name required in the address of all mail being delivered to Puerto Rico. Empty string if not present
    zip_code string
    5-digit ZIP Code and the four additional digits
  - count number
    The number of addresses we matched to the input. We return the closest match by default.
  - fit number
    A score represented as number between 1 and 0. Fit compares the address elements present in your query against the matching address elements. It does not incorporate elements you have not presented in the score. A partial address (e.g. 123 Main St) will have a fit of 1 even though it is missing city and zip code. Its confidence score will be less than 1 however because it is missing some crucial elements.
  - confidence number
    A confidence score represented as number between 1 and 0. 1 indicates a full match. 0 indicates no complete matching elements.
  - match_information string
    Additional information about the match.
    
    This information is for human consumption and may not be present in all responses.
    Example
    Single Response - The delivery address was found in the National Database and no further information was required.
  - address_line_one string
    Primary delivery address
    Example
    123 Main St
  - address_line_two string
    Secondary address information
  - city string
    City name
    Example
    Springfield
  - state string
    State name
    Example
    CO
  - zip_code string
    Zip code
    Example
    81073-1119
  - country_iso_2 string
    2 letter ISO country code
    Example
    US
- UsaVerifyNoMatch
  - query string
    Originally submitted query
  - query_city string
    Originally submitted city
  - query_state string
    Originally submitted state
  - query_zip_code string
    Originally submitted zip_code
  - match object
    Nearest matching address
    Values
    "null"
  - count number
    Values
    0
  - fit number
    Format
    float
    Values
    0
  - confidence number
    Format
    float
    Values
    0
  - address_line_one string
    Empty if no match
    Values
    ""
  - address_line_two string
    Empty if no match
    Values
    ""
  - city string
    Empty if no match
    Values
    ""
  - state string
    Empty if no match
    Values
    ""
  - zip_code string
    Empty if no match
    Values
    ""
  - country_iso_2 string
    Empty if no match
    Values
    ""

Request

curl
JavaScript
Python
Ruby
PHP

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

const response = await fetch('https://api.addresszen.com/v1/verify/addresses', {
  method: 'POST',
  headers: {
    'Authorization': 'api_key="ak_test"',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: '123 Main St, Springfield, IL 62701',
  }),
});

const { result } = await response.json();

import requests

response = requests.post(
    "https://api.addresszen.com/v1/verify/addresses",
    headers={"Authorization": 'api_key="ak_test"'},
    json={
        "query": "123 Main St, Springfield, IL 62701",
    },
)
result = response.json()["result"]

require "net/http"
require "json"

uri = URI("https://api.addresszen.com/v1/verify/addresses")
body = {
  query: "123 Main St, Springfield, IL 62701",
}
response = Net::HTTP.post(uri, body.to_json, "Authorization" => 'api_key="ak_test"', "Content-Type" => "application/json")
result = JSON.parse(response.body)["result"]

<?php
$ch = curl_init("https://api.addresszen.com/v1/verify/addresses");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: api_key="ak_test"', "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode([
    "query" => "123 Main St, Springfield, IL 62701",
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true)["result"];

Body

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

Response

200 OK

{
  "code": 2000,
  "message": "Success",
  "result": {
    "query": "",
    "query_city": "",
    "query_state": "",
    "query_zip_code": "",
    "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"
    },
    "count": 0,
    "fit": 0,
    "confidence": 0,
    "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",
    "address_line_two": "",
    "city": "Springfield",
    "state": "CO",
    "zip_code": "81073-1119",
    "country_iso_2": "US"
  }
}

Countries

Query parameters​

Request body​

Response​

Query parameters

Request body

Response