# 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`. ## Example request **curl** ```bash 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" }' ``` **JavaScript** ```javascript 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(); ``` **Python** ```python 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"] ``` **Ruby** ```ruby 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** ```php 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"]; ``` ## Example body ```json { "query": "123 Main St, Springfield, CO 81073", "zip_code": "81073-1119", "city": "Springfield", "state": "CO" } ``` ## Example response **200 OK** ```json { "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" } } ``` ## 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](/docs/api/api-reference.md) 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 * `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 | Field | Type | Description | | ------------------ | ------ | ---------------------------------------- | | `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: "" |