US Street Address API

This page describes how to verify one or more addresses using the SmartyStreets US Street Address API. You may want to try it out with a free testing account. We also offer a less-technical lookup tool for validating addresses.


  1. HTTP Request
    1. URL Composition
    2. Supported Methods/Verbs
    3. Input Fields
    4. Headers
  2. HTTP Response
    1. Status Codes and Results
    2. Output Field Definitions
  3. Supplementary Materials
    1. SSL/TLS Information
    2. Try the demo

HTTP Request: URL Composition

Proper URL construction is required for all API requests. Here is an example URL:

Here is a more granular examination of the example above:

URL ComponentsValuesNotes
SchemehttpsNOTE: non-secure http requests are not supported
Query String?auth-id=123&auth-token=abcAuthentication information, inputs, etc. Additional query string parameters are introduced in the next section.

For additional information, please read our article about URL components.

HTTP Request: Supported Methods/Verbs

Supported HTTP Methods

HTTP requests can be categorized according to their HTTP method. Most HTTP requests are defined using the GET method. We call these "get requests". Other common methods are PUT, POST, and DELETE.

The following methods are supported by this API:

Note: When calling any of our APIs using "Website Key" authentication, only the HTTP GET method is allowed. With "Secret Key" authentication, both HTTP GET and POST methods are allowed.

HTTP GET: Single Address

To send one (and only one) address to our API, simply encode the input field names from the table below along with the corresponding input values as query string parameters in the URL of your request. Here's an example that uses the street, city, state, and candidates fields:

curl -v '

Please note that all query string parameter values must be url-encoded (spaces become + or %20, for example) to ensure that the data is transferred correctly. A common mistake we see is a non-encoded pound sign (#) like in an apartment number (# 409). This character, when properly encoded in a URL, becomes %23. When not encoded this character functions as the fragment identifier, which is ignored by our API servers.

HTTP POST: Multiple Addresses

A POST request allows a larger volume of data (MAX: 100 addresses or 32K per request) to be sent in the HTTP Request Body. In this case, the data should be encoded as a JSON array where each element in the array is a JSON object with field names identical to those in the field listing below. Here's a sample request with two addresses being sent:

curl -v '
	-H "Content-Type: application/json"
	--data-binary '
			"street":"1 Santa Claus",
			"city":"North Pole",
			"addressee":"Apple Inc",
			"street":"1 infinite loop",

HTTP Request: Input Fields

Each address submitted must have non-blank values for one of the following field combinations to be eligible for a positive address match:

  • street + city + state
  • street + zipcode
  • street (entire address in the street field - what we call a "freeform" input)
NameTypeMax CharactersDefault ValueDescription
input_idstring36blankA unique identifier for this address used in your application; this field will be copied into the output.
streetstring64blankThe street line of the address, or the entire address ("freeform" input). Freeform inputs should NOT include any form of country information (like "USA").
street2string64blankAny extra address information
(e.g., Leave it on the front porch.)
secondarystring32blankApartment, suite, or office number
(e.g., "Apt 52" or simply "52"; not "Apt52".)
citystring64blankThe city name
statestring32blankThe state name or abbreviation
zipcodestring16blankThe ZIP Code
lastlinestring64blankCity, state, and ZIP Code combined
addresseestring64blankThe name of the recipient, firm, or company at this address
urbanizationstring64blankOnly used with Puerto Rico
candidatesintegerMax Value: 101The maximum number of valid addresses returned when the input is ambiguous
matchstring8blankThe match strategy to be employed for this lookup. This input field overrides, for this lookup, any match strategy assigned via optional HTTP headers. Valid values are:
  • [blank]
  • strict
  • range
  • invalid

Match Strategy

The following client-specified strategies determine how matches are made and what kind of results are returned.

The default match strategy. Results returned are guaranteed to be DPV confirmed. Input that doesn't match an actual delivery point will produce empty output.
A somewhat more inclusive match strategy that includes more than just verified results by standardizing addresses where the primary numbers fit into the range on the street.
Note: This match strategy is not compatible with freeform addresses and is ignored for those inputs.
The most inclusive/aggressive match strategy, which may include results for addresses that are not even remotely valid. As a side-effect, ambiguous addresses return only one candidate result, not multiple.
Note: This match strategy is not compatible with freeform addresses and is ignored for those inputs.

HTTP Request: Headers

You must include the following required HTTP headers in all requests:

Content-TypeThe purpose of the Content-Type field is to describe the data contained in the body fully enough that the receiving user agent can pick an appropriate agent or mechanism to present the data to the user, or otherwise deal with the data in an appropriate manner.Content-Type: application/json
HostThe Host request header field specifies the internet host and port number of the resource being requestedHost:

HTTP Response: Status Codes and Results

Responses will have a status header with a numeric value. This value is what you should check for when writing code to parse the response. The only response body that should be read and parsed is a 200 response.

Status CodeResponse and Explanation
401Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.
413Request Entity Too Large: The maximum size for a request body to this API is 32K (32,768 bytes).
400Bad Request (Malformed Payload): A GET request lacked a street field or the request body of a POST request contained malformed JSON.
429Too Many Requests: When using public "website key" authentication, we restrict the number of requests coming from a given source over too short of a time. If you use "website key" authentication, you can avoid this error by adding your IP address as an authorized host for the website key in question.
200OK (success!): A JSON array containing zero or more address matches for the input provided with the request. If none of the submitted addresses validate, the array will be empty ([]). The structure of the response is the same for both GET and POST requests.

JSON Response

Rather than writing your own code to parse the JSON response, we recommend using a tried and tested JSON parser that is specific for your programming language. There is a very comprehensive list of such tools (as well as the complete JSON specification) at

Example Output - Valid Address

        "input_index": 0,
        "candidate_index": 0,
        "delivery_line_1": "1 Santa Claus Ln",
        "last_line": "North Pole AK 99705-9901",
        "delivery_point_barcode": "997059901010",
        "components": {
            "primary_number": "1",
            "street_name": "Santa Claus",
            "street_suffix": "Ln",
            "city_name": "North Pole",
            "state_abbreviation": "AK",
            "zipcode": "99705",
            "plus4_code": "9901",
            "delivery_point": "01",
            "delivery_point_check_digit": "0"
        "metadata": {
            "record_type": "S",
            "zip_type": "Standard",
            "county_fips": "02090",
            "county_name": "Fairbanks North Star",
            "carrier_route": "C004",
            "congressional_district": "AL",
            "rdi": "Commercial",
            "elot_sequence": "0001",
            "elot_sort": "A",
            "latitude": 64.75233,
            "longitude": -147.35297,
            "precision": "Zip8",
            "time_zone": "Alaska",
            "utc_offset": -9,
            "dst": true
        "analysis": {
            "dpv_match_code": "Y",
            "dpv_footnotes": "AABB",
            "dpv_cmra": "N",
            "dpv_vacant": "N",
            "active": "Y",
            "footnotes": "L#"

		"input_index": 1,
		"candidate_index": 0,
		"addressee": "Apple Inc",
		"delivery_line_1": "1 Infinite Loop",
		// truncated for brevity

Example Output - Invalid Address


HTTP Response: Output field definitions

Root  |  Components  |  Metadata  |  Analysis  |  Footnotes


Field NameTypeDefinition
input_idvarchar(36)Any unique identifier that you use to reference the input address; the output will be identical to the input.
input_indexintThe order in which this address was submitted with the others
(0 if alone)
candidate_indexintAn input address can match multiple valid addresses. This ties the candidates to the input index.
(e.g., "1 Rosedale Street Baltimore Maryland" will return multiple candidates.)
addresseevarchar(50)Will usually contain a firm name; intended recipient at an address
delivery_line_1varchar(50)Contains the first delivery line (usually the street address). This can include any of the following:
  • Primary Number
  • Street Name
  • Street Predirection
  • Street Postdirection
  • Street Suffix
  • Secondary Number
  • Secondary Designator
  • PMB Designator
  • PMB Number
delivery_line_2varchar(50)The second delivery line (if needed). It is common for this field to remain empty, but it may contain a private mailbox number.
last_linevarchar(50)City, state, and ZIP Code combined
delivery_point_barcodevarchar(12)12-digit POSTNET™ barcode; consists of 5-digit ZIP Code, 4-digit add-on code, 2-digit delivery point, and 1-digit check digit.
components[Object]See "Components" table below.
metadata[Object]See "Metadata" table below.
analysis[Object]See "Analysis" table below.


Field NameTypeDefinition
urbanizationvarchar(64)Primarily for Puerto Rican addresses; a very important component which contains area, sector, or development within a geographic area; should be included after the name of the recipient
primary_numbervarchar(30)The house, PO Box, or building number
street_namevarchar(64)The name of the street
street_predirectionchar(16)Directional information before a street name (N, SW, etc.)
street_postdirectionchar(16)Directional information after a street name (N, SW, etc.)
street_suffixchar(16)Abbreviated value describing the street (St, Ave, Blvd, etc.)
secondary_numbervarchar(32)Apartment or suite number, if any
secondary_designatorvarchar(16)Describes location within a complex/building (Ste, Apt, etc.)
extra_secondary_numbervarchar(32)Descriptive information about the location of a building within a campus
(e.g., E-5 in "5619 Loop 1604, Bldg E-5, Ste. 101 San Antonio TX")
extra_secondary_designatorvarchar(16)Description of the location type within a campus
(e.g., Bldg, Unit, Lot, etc.)
pmb_designatorvarchar(16)Private mailbox unit designator (assigned by a CMRA)
pmb_numbervarchar(16)The private mailbox number, assigned by a CMRA
city_namevarchar(64)The accepted/proper name of the city
default_city_namevarchar(64)The default city name for the address. This field will not be present if the default city name is equal to the value of the city name field.
state_abbreviationchar(2)The two-letter state abbreviation
zipcodechar(5)The 5-digit ZIP Code
plus4_codechar(4)The 4-digit add-on code (more specific than 5-digit ZIP)
delivery_pointchar(2)The last two digits of the house/box number, unless an "H" record is matched, in which case this is the secondary unit number representing the delivery point information to form the delivery point barcode (DPBC).
delivery_point_check_digitchar(1)Correction character, or check digit, for the 11-digit barcode


Field NameTypeDefinition
record_typechar(1)Indicates the type of record that was matched. Only given if a DPV match is made.

F — Firm; the finest level of match available for an address
G — General Delivery; for mail to be held at local post offices
H — High-rise; address contains apartment or building sub-units.
P — Post Office box; address is a PO Box record type.
R — Rural Route or Highway Contract; may have box number ranges.
S — Street; address contains a valid primary number range.
[blank] — No record type because address did not make a valid DPV match
zip_typevarchar(32)Indicates the type of the ZIP Code for the address that was matched. Only given if a 5-digit match is made.

Unique — The ZIP Code consists of a single delivery point, pertaining to a United States Postal Service customer (like a large business or government agency) that routes all of its own mail internally.
Military — The ZIP Code pertains to military units and diplomatic organizations, often in foreign locations.
POBox — The ZIP Code is assigned to a collection of Post Office Boxes.
Standard — The ZIP Code does not pertain to any of the above categories.
county_fipschar(5)The 5-digit county FIPS (Federal Information Processing Standards) code. It is a combination of a 2-digit state FIPS code and a 3-digit county code assigned by the NIST (National Institute of Standards and Technology).
county_namevarchar(64)The name of the county the address is in
carrier_routechar(4)The postal carrier route for the address
congressional_districtchar(2)The congressional district to which the address belongs. Output will be two digits from 01 - 53 or "AL." "AL" means that the entire state (or territory) is covered by a single congressional district. These include Alaska, Delaware, Montana, North Dakota, South Dakota, Vermont, Wyoming, Washington DC, Virgin Islands, and other territories.
building_default_indicatorchar(1)Indicates whether the address is the "default" address for a building; for example, the main lobby
rdivarchar(12)Residential Delivery Indicator (residential or commercial)

Residential — The address is a residential address.
Commercial — The address is a commercial address.
[blank] — This happens when the address is invalid and we don't have enough information to ascertain RDI status. The SmartyList tools translate a [blank] RDI value to "Unknown".

Note: For some reason, known only to the US Postal Service, PO Boxes are always marked as "Residential".
elot_sequencevarchar(4)eLOT (Enhanced Line of Travel) 4-digit sequence number
elot_sortvarchar(4)eLOT (Enhanced Line of Travel) product was developed to give mailers the ability to sort their mailings by line of travel sequence.

A — Ascending
D — Descending
[blank] — Address not submitted for eLOT

latitudedecimal(12,9)The horizontal component used for geographic positioning. It is the angle between 0° (the equator) and ±90° (north or south) at the poles. It is the first value in an ordered pair of (latitude, longitude). A negative number denotes a location below the equator; a positive number is above the equator. Combining lat/long values enables you to pinpoint addresses on a map.
longitudedecimal(12,9)The vertical component used for geographic positioning. It is the angle between 0° (the Prime Meridian) and ±180° (westward or eastward). It is the second number in an ordered pair of (latitude, longitude). A negative number indicates a location west of Greenwich, England; a positive number east. Combining lat/long values enables you to pinpoint addresses on a map.
precisionvarchar(18)Indicates the precision of the latitude and longitude values.

Unknown — Coordinates not known, possibly because address is invalid
None — Coordinates are not provided for this address. Military addresses such as APO, FPO, and DPO do not provide coordinates.
State — Reserved for future use
SolutionArea — Reserved for future use
City — Reserved for future use
Zip5 — Accurate to a 5-digit ZIP Code level (least precise)
Zip6 — Accurate to a 6-digit ZIP Code level
Zip7 — Accurate to a 7-digit ZIP Code level
Zip8 — Accurate to an 8-digit ZIP Code level
Zip9 — Accurate to a 9-digit ZIP Code level (most precise but NOT rooftop level)
Structure — Reserved for future use

Note: Concerning addresses for which the ZIP9 precision is not available, the ZIP# precision is interpolated based on neighboring addresses. Thus, ZIP7 is an average of all the lat/long coordinates of nearby ZIP Codes that share those first 7 digits.
time_zonevarchar(48)Indicates the common name of the time zone associated with the address.

Valid Responses
Alaska, Atlantic, Central, Eastern, Hawaii, Mountain, None, Pacific, Samoa, UTC+9, UTC+10, UTC+11, UTC+12
utc_offsetdecimal(4,2)Indicates the number of hours the time zone is offset from Universal Time Coordinated (UTC), the international time standard, also known as Greenwich Meridian Time (GMT).

Valid Responses
-11, -10, -9, -8, -7, -6, -5, -4, 0, 9, 10, 11, 12
dstchar(5)Indicates if the time zone "obeys," or, in other words, adjusts their clocks forward and back with the seasons. This information is particularly useful to determine time in other time zones with areas that may or may not use daylight saving time - for example, Arizona, Hawaii, and, of all places, Indiana.

true — Time zone observes daylight saving time.

If dst is absent from the response, then time zone does not observe daylight saving time.


Field NameTypeDefinition
dpv_match_codevarchar(1)Status of the Delivery Point Validation (DPV). This lets you know if the USPS delivers mail to the address.

Y — Confirmed; entire address was DPV confirmed deliverable.
(e.g., 1600 Amphitheatre Pkwy Mountain View, CA)
N — Not Confirmed; address could not be DPV confirmed as deliverable.
S — Confirmed By Dropping Secondary; address was DPV confirmed by dropping secondary info (apartment, suite, etc.).
(e.g., 62 Ea Darden Dr Apt 298 Anniston, AL)
D — Confirmed - Missing Secondary Info; the address was DPV confirmed, but it is missing secondary information (apartment, suite, etc.).
(e.g., 122 Mast Rd Lee, NH)
[blank] — The address was not submitted for DPV. This is usually because the address does not have a ZIP Code and a +4 add-on code, or the address has already been determined to be Not Deliverable (only returned as part of the XML response).
dpv_footnotesvarchar(32)Indicates why the address was given its DPV value and potentially the type of ZIP Code that was matched. All these footnotes have a length of 2 characters, and there may be up to 14 footnotes.

AA — City/state/ZIP + street are all valid.
(e.g., 2335 S State St Ste 300 Provo UT)
A1 — ZIP+4 not matched; address is invalid. (City/state/ZIP + street don't match.)
(e.g., 3214 N University Ave New York NY)
BB — ZIP+4 matched; confirmed entire address; address is valid.
(e.g., 2335 S State St Ste 300 Provo UT)
CC — Confirmed address by dropping secondary (apartment, suite, etc.) information.
(e.g., 2335 S State St Ste 500 Provo UT)
F1 — Matched to military or diplomatic address.
(e.g., Unit 2050 Box 4190 APO AP 96278)
G1 — Matched to general delivery address.
(e.g., General Delivery Provo UT 84604)
M1 — Primary number (e.g., house number) is missing.
(e.g., N University Ave Provo UT)
M3 — Primary number (e.g., house number) is invalid.
(e.g., 16 N University Ave Provo UT)
N1 — Confirmed with missing secondary information; address is valid but it also needs a secondary number (apartment, suite, etc.).
(e.g., 2335 S State St Provo UT)
P1 — PO, RR, or HC box number is missing.
(e.g., RR 5 Cadiz KY)
P3 — PO, RR, or HC box number is invalid.
(e.g., RR 5 Box 1000 Cadiz KY)
RR — Confirmed address with private mailbox (PMB) info.
(e.g., 3214 N university ave #409 Provo UT)
R1 — Confirmed address without private mailbox (PMB) info.
(e.g., 3214 N university ave Provo UT)
U1 — Matched a unique ZIP Code.
(e.g., 100 North Happy Street 12345)
Here are some common combinations:
  • AABB - ZIP, state, city, street, and primary number match.
  • AAM1 - ZIP, state, city, and street match, but the primary number is missing.
  • AAM3 - ZIP, state, city, and street match, but the primary number is invalid.
  • AAN1 - ZIP, state, city, street, and primary number match, but there is secondary information such as apartment or suite that would be helpful.
  • A1 - Just plain bad address; can't match street to city/state/ZIP combination
  • AABBR1 - ZIP, state, city, street, and primary number match. Address confirmed without private mailbox (PMB) info.
dpv_cmravarchar(1)Indicates whether the address is associated with a Commercial Mail Receiving Agency (CMRA), also known as a private mailbox (PMB) operator. A CMRA is a business through which USPS mail may be sent or received, for example the UPS Store and Mailboxes Etc.

Y — Address is associated with a valid CMRA.
N — Address is not associated with a valid CMRA.
[blank] — Address was not submitted for CMRA verification.
dpv_vacantvarchar(1)Indicates that a delivery point was active in the past but is currently vacant (in most cases, unoccupied over 90 days) and is not receiving deliveries. This status is often obtained when mail receptacles aren't being emptied and are filling up, so mail is held at the post office for a certain number of days before the delivery point is marked vacant.

Y — Address is vacant.
N — Address is not vacant.
[blank] — Address was not submitted for vacancy verification.
activevarchar(1)Indicates whether the address is active, or "in-service" according to the USPS. Examples: New developments may have addresses but will be "inactive" until somebody moves in. Or, after Hurricane Katrina, addresses in the affected area were marked as inactive for a time. Residents may also mark their own mailboxes as inactive for privacy and other reasons.

Y — Address is active.
N — Address is inactive.
[blank] — Activity status is not known by the USPS.
ews_matchchar(5)Early warning system flag; a positive result indicates the street of the address is not yet ready for mail delivery and that the address will soon be added to the master ZIP+4 file in the coming weeks or months. This commonly occurs for new streets or streets undergoing a name change.

true — The address was flagged by EWS, preventing a ZIP+4 match.
[blank] — Address was not flagged by EWS.
footnotesvarchar(12)Indicates which changes were made to the input address. Footnotes are delimited by a # character. See the footnotes table below for details.
lacslink_codevarchar(2)The reason for the LACSLink indication that was given (below)

A — Match: Address provided. LACSLink record match was found, and a converted address was provided.
00 — No Match. No converted address. No soup for you!
09 — Match: No new address. LACSLink matched an input address to an old address which is a "high-rise default" address; no new address was provided.
14 — Match: No conversion. Found a LACSLink record, but couldn't convert the data to a deliverable address.
92 — Match: Dropped secondary number. LACSLink record was matched after dropping the secondary number from input.
[blank] — No LACSLink lookup attempted.
lacslink_indicatorvarchar(1)Indicates whether there is an address match in the LACSLink database.

Y — LACS record match; a new address could be furnished because the input record matched a record in the master file.
S — LACS record - secondary number dropped; the record is a ZIP+4 street level or high-rise match. The input record matched a master file record, but the input address had a secondary number and the master file record did not.
N — No match; a new address could not be furnished; the input record could not be matched to a record in the master file.
F — False positive; a false positive record was detected.
[blank] — No LACSLink lookup attempted.
suitelink_matchvarchar(5)Indicates a match (or not) to the USPS SuiteLink data. SuiteLink attempts to provide secondary information such as "suite" or "apartment" whenever there is a match based on address and Firm Name (Company) input.

true — There was a SuiteLink match and the result is provided.
false — There was no SuiteLink match.


This table describes possible values in the footnotes field from the analysis object.
(Example addresses may be changed at any time due to the nature of the data.)

A#Corrected ZIP CodeThe address was found to have a different 5-digit ZIP Code than given in the submitted list. The correct ZIP Code is shown in the ZIP Code field.
(e.g., 4800 Fairmount Ave Kansas City MO 64111)
B#Fixed city/state spellingThe spelling of the city name and/or state abbreviation in the submitted address was found to be different than the standard spelling. The standard spelling of the city name and state abbreviation is shown in the City and State fields.
(e.g., 39 Main Street Roeblong NJ 08554)
C#Invalid city/state/ZIPThe ZIP Code in the submitted address could not be found because neither a valid city and state, nor valid 5-digit ZIP Code was present. SmartyStreets recommends that the customer check the accuracy of the submitted address.
(e.g., 200 Camp Drive, 25816)
D#No ZIP+4 assignedThis is a record listed by the United States Postal Service as a non-deliverable location. SmartyStreets recommends that the customer check the accuracy of the submitted address.
(e.g., 39 Main Street Roeblong NJ 08554)
E#Same ZIP for multipleMultiple records were returned, but each shares the same 5-digit ZIP Code.
(e.g., 1 Rosedale Baltimore MD)
F#Address not foundThe address, exactly as submitted, could not be found in the city, state, or ZIP Code provided. Many factors contribute to this; either the primary number is missing, the street is missing, or the street is too horribly misspelled to understand.
(e.g., 2600 Rafe Lane Jackson MS 39201)
G#Used firm dataInformation in the firm line was determined to be a part of the address. It was moved out of the firm line and incorporated into the address line.
(e.g., 14315 50th Pl N, First Union, Plymouth MN 55446)
H#Missing secondary numberZIP+4 information indicates that this address is a building. The address as submitted does not contain a secondary (apartment, suite, etc.) number. SmartyStreets recommends that the customer check the accuracy of the submitted address and add the missing secondary number to ensure the correct Delivery Point Barcode (DPBC).
(e.g., 109 Wimbledon Sq Chesapeake, VA 23320)
I#Insufficient/ incorrect address dataMore than one ZIP+4 Code was found to satisfy the address as submitted. The submitted address did not contain sufficiently complete or correct data to determine a single ZIP+4 Code. SmartyStreets recommends that the customer check the accuracy and completeness of the submitted address. For example, a street may have a similar address at both the north and south ends of the street.
(e.g., 1 Rosedale Baltimore MD 21229)
J#Dual addressThe input contained two addresses. For example: 123 MAIN ST PO BOX 99.
(e.g., PO Box 38606 30th Street Train Station Philadelphia PA 19104)
K#Cardinal rule matchAlthough the address as submitted is not valid, we were able to find a match by changing the cardinal direction (North, South, East, West). The cardinal direction we used to find a match is found in the components.
(e.g., 315 W Cesar Chavez St Austin TX)
L#Changed address componentAn address component (i.e., directional or suffix only) was added, changed, or deleted in order to achieve a match.
(e.g., 173 Broadway Salt Lake UT 84101)
Flagged address for LACSLinkThe input address matched a record that was LACS-indicated, that was submitted to LACSLink for processing. This does not mean that the address was converted; it only means that the address was submitted to LACSLink because the input address had the LACS indicator set.
M#Fixed street spellingThe spelling of the street name was changed in order to achieve a match.
(e.g., 3308 Fountainviuw Monsey NY)
N#Fixed abbreviationsThe delivery address was standardized. For example, if STREET was in the delivery address, SmartyStreets will return ST as its standard spelling.
(e.g., 2438 Brown Avenue Knoxville TN 37917)
O#Multiple ZIP+4; lowest usedMore than one ZIP+4 Code was found to satisfy the address as submitted. The lowest ZIP+4 add-on may be used to break the tie between the records.
(e.g., RR 2 Box 132 Wolf Summit WV 26426)
P#Better address existsThe delivery address is matchable, but it is known by another (preferred) name. For example, in New York, NY, AVENUE OF THE AMERICAS is also known as 6TH AVE. An inquiry using a delivery address of 39 6th Avenue would be flagged with Footnote P.
(e.g., 131 Stone Farm Lebanon NH 03766)
Q#Unique ZIP matchMatch to an address with a unique ZIP Code
(e.g., 645 Swick Hill Street Charlotte NC 28263)
R#No match; EWS: Match soonThe delivery address is not yet matchable, but the Early Warning System file indicates that an exact match will be available soon.
(e.g., 1644 CR 1800E PMB 17420, Arthur IL 61911)
S#Bad secondary addressThe secondary information (apartment, suite, etc.) does not match that on the national ZIP+4 file. The secondary information, although present on the input address, was not valid in the range found on the national ZIP+4 file.
(e.g., 1409 Hueytown Rd Apt 1781 Bessemer AL 35023)
T#Multiple response due to magnet street syndromeThe search resulted in a single response; however, the record matched was flagged as having magnet street syndrome, and the input street name components (pre-directional, primary street name, post-directional, and suffix) did not exactly match those of the record. A "magnet street" is one having a primary street name that is also a suffix or directional word, having either a post-directional or a suffix (i.e., 2220 PARK MEMPHIS TN logically matches to a ZIP+4 record 2200-2258 PARK AVE MEMPHIS TN 38114-6610), but the input address lacks the suffix "AVE" which is present on the ZIP+4 record. The primary street name "PARK" is a suffix word. The record has either a suffix or a post-directional present. Therefore, in accordance with CASS requirements, a ZIP+4 Code must not be returned. The multiple response return code is given since a "no match" would prevent the best candidate.
(e.g., 84 Green St Northampton MA)
U#Unofficial post office nameThe city or post office name in the submitted address is not recognized by the United States Postal Service as an official last line name (preferred city name), and is not acceptable as an alternate name. The preferred city name is included in the City field.
(e.g., 9894 Bissonnet St #723 Sharpstown TX 77036)
V#Unverifiable city / stateThe city and state in the submitted address could not be verified as corresponding to the given 5-digit ZIP Code. This comment does not necessarily denote an error; however, SmartyStreets recommends that the customer check the accuracy of the city and state in the submitted address.
(e.g., 107 Kerwood St Kildeer IL 60067)
W#Invalid delivery addressThe input address record contains a delivery address other than a PO Box, General Delivery, or Postmaster 5-digit ZIP Code that is identified as a "small town default". The USPS does not provide street delivery service for this ZIP Code. The USPS requires the use of a PO Box, General Delivery, or Postmaster for delivery within this ZIP Code.
X#Unique ZIP CodeDefault match inside a unique ZIP Code
(e.g., 609 Pheasant Ridge Road Wayne PA 19088)
Y#Military matchMatch made to a record with a military or diplomatic ZIP Code.
(e.g., PSC 10 Box 1324 APO AE 09142)
Z#Matched with ZIPMOVEThe ZIPMOVE product shows which ZIP+4 records have moved from one ZIP Code to another. If an input address matches a ZIP+4 record which the ZIPMOVE product indicates has moved, the search is performed again in the new ZIP Code.
(e.g., 4928 HERITAGE XING DR SW Hiram GA 30141)

XML usage

While we prefer JSON for its flexibility and ease of use, our API will still accept and return XML data. To send XML in a POST request, set the Content-Type request header to application/xml. To receive XML in the response, set the Accept request header to application/xml. Here's a simple example:

curl -v -X POST '
	-H 'Content-Type: application/xml'
	-H 'Accept: application/xml'
	--data-binary '
	        <addressee>Apple Inc</addressee>
	        <street>1 infinite loop</street>
	        <street2>po box 42</street2>
	        <street>1600 Pennsylvania ave</street>
	        <street>123 main st. 12345</street>

SSL/TLS Information

Use Modern Security Software and Cipher Suites
Certificate Authority:
	AddTrust External CA Root
	Fingerprint: 02faf3e291435468607857694df5e45b68851868

Supported Protocols:
	TLS 1.2
	TLS 1.1
	TLS 1.0

Cipher Suites:

Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff