Verify addresses

This page describes how to verify one or more addresses using the SmartyStreets API.

Contents

  1. Input fields
  2. Headers
  3. Single address
  4. Multiple addresses
  5. Response
  6. Output fields

Input fields

The minimum requirements for a positive address match are: street + city + state OR street + zipcode

Name Type Max Characters Description
input_id string 16 A unique identifier for this address used in your application; this field will be copied into the output
street string 64 The street line of the address, or an entire address
street2 string 64 Any extra address information
secondary string 32 Apartment, suite, or office number
city string 64 The city name
state string 32 The state name or abbreviation
zipcode string 16 The ZIP Code
lastline string 64 City, state, and ZIP Code combined
addressee string 64 The name of the recipient, firm, or company at this address
urbanization string 64 Only used with Puerto Rico
candidates integer Max Value: 10 The maximum number of valid addresses returned when the input is ambiguous.

Headers

You may use the following optional HTTP headers in your requests:

Header Description Example
X-Standardize-Only Includes more than just verified results by standardizing addresses where the primary numbers fit into the range on the street.

Note: This header is not compatible with freeform addresses.
X-Standardize-Only: true
X-Include-Invalid Activates the most aggressive matching mode, 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 header is not compatible with freeform addresses.
X-Include-Invalid: true

Single address

To submit one address at a time, a simple HTTPS GET request is all you need.

curl -v 'https://api.smartystreets.com/street-address?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE&
	street=1+Santa+Claus&
	city=North+Pole&
	state=AK&
	candidates=10'

Multiple addresses

In order to submit multiple addresses at a time (MAX: 100 addresses per request) you can use an HTTPS POST request.

curl -v 'https://api.smartystreets.com/street-address?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE' --data-binary '
[
	{
		"street":"1 Santa Claus",
		"city":"North Pole",
		"state":"AK",
		"candidates":10
	},
	{
		"addressee":"Apple Inc",
		"street":"1 infinite loop",
		"city":"cupertino",
		"state":"CA",
		"zipcode":"95014",
		"candidates":10
	}
]'

Response

Every response is a JSON array containing zero or more address matches for your input. If none of the submitted addresses validate, the array is empty []. The structure is the same whether you use GET or POST requests.

[
	{
		"input_index": 0,
		"candidate_index": 0,
		"addressee": "Apple Inc",
		"delivery_line_1": "1 Infinite Loop",
		"delivery_line_2": "PO Box 42",
		"last_line": "Cupertino CA 95014-2083",
		"delivery_point_barcode": "950142083017",
		"components": {
			"primary_number": "1",
			"street_name": "Infinite",
			"street_suffix": "Loop",
			"city_name": "Cupertino",
			"state_abbreviation": "CA",
			"zipcode": "95014",
			"plus4_code": "2083",
			"delivery_point": "01",
			"delivery_point_check_digit": "7"
		},
		"metadata": {
			"record_type": "S",
			"county_fips": "06085",
			"county_name": "Santa Clara",
			"carrier_route": "C067",
			"congressional_district": "15",
			"rdi": "Commercial",
			"latitude": 37.33118,
			"longitude": -122.03062,
			"precision": "Zip9"
		},
		"analysis": {
			"dpv_match_code": "Y",
			"dpv_footnotes": "AABB",
			"dpv_cmra": "N",
			"dpv_vacant": "N",
			"active": "Y"
		}
	}
]

Output fields

Root  |  Components  |  Metadata  |  Analysis  |  Footnotes

Root

Field Name Type Definition
input_id varchar(16) Any unique identifier that you use to reference the input address. The output will be identical to the input.
input_index int The order in which this address was submitted with the others
(0 if alone)
candidate_index int An input address can match multiple valid addresses. This ties the candidates to the input index.
(eg. "1 Rosedale Street Baltimore Maryland" will return multiple candidates.)
addressee varchar(50) Will usually contain a firm name; intended recipient at an address
delivery_line_1 varchar(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_2 varchar(50) The second delivery line (if needed); it is common for this field to remain empty, but it may contain a private mail box number
last_line varchar(50) City, state, and ZIP Code combined
delivery_point_barcode varchar(12) 12-digit POSTNET™ barcode. Consists of 5-digit ZIP code, 4-digit addon 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

Components

Field Name Type Definition
urbanization varchar(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_number varchar(30) The house, PO Box, or building number
street_name varchar(64) The name of the street
street_predirection char(16) Directional information before a street name (N, SW, etc.)
street_postdirection char(16) Directional information after a street name (N, SW, etc.)
street_suffix char(16) Abbreviated value describing the street (St, Ave, Blvd, etc.)
secondary_number varchar(32) Apartment or suite number, if any
secondary_designator varchar(16) Describes location within a complex/building (Ste, Apt, etc.)
extra_secondary_number varchar(32) Descriptive information about the location of a building within a campus
(eg. E-5 in "5619 Loop 1604, Bldg E-5, Ste. 101 San Antonio TX)
extra_secondary_designator varchar(16) Description of the location type within a campus (e.g. Bldg, Unit, Lot, etc.)
pmb_designator varchar(16) Private mail box unit designator (assigned by a CMRA)
pmb_number varchar(16) The private mail box number, assigned by a CMRA
city_name varchar(64) The accepted/proper name of the city
default_city_name varchar(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_abbreviation char(2) The two-letter state abbreviation
zipcode char(5) The 5-digit ZIP Code
plus4_code char(4) The 4-digit add-on code (more specific than 5-digit ZIP)
delivery_point char(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_digit char(1) Correction character, or check-digit, for the 11-digit barcode

Metadata

Field Name Type Definition
record_type char(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_type varchar(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 is assigned to an address that receives a high volume of mail. All delivery lines are routed internally by the assigned organization.
Military — The ZIP Code pertains to military units, often deployed to 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_fips char(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_name varchar(64) The name of the county the address is in
carrier_route char(4) The postal carrier route for the address
congressional_district char(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_indicator char(1) Indicates whether the address is the "default" address for a building; for example, the main lobby
rdi varchar(12) Residential Delivery Indicator (residential or commercial).

residential — The address is a residential address
commercial — The address is a commercial address
unknown — The RDI of the address is currently unknown
elot_sequence varchar(4) eLOT (Enhanced Line of Travel) 4-digit sequence number.
elot_sort varchar(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

latitude decimal(9,6) 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/lon values enables you to pinpoint addresses on a map.
longitude decimal(9,6) 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/lon values enables you to pinpoint addresses on a map.
precision varchar(18) Indicates the precision of the latitude & 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 a 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: addresses for which the ZIP9 precision is not available, the ZIP# precision in interpolated based on neighboring addresses. Thus, ZIP7 is an average of all the lat/lon coordinates of nearby ZIP codes that share those first 7 digits
time_zone varchar(48) Indicates the common name of the timezone associated with the address.

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

Valid Responses
(-9, -4, -6, -5, -10, -7, 0, -8, -11, 10, 11, 12, 9)
dst char(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 savings time - for example, Arizona, Hawaii, and, of all places - Indiana.

true — Time zone observes Daylight Savings Time

If dst is absent from the response, then time zone does not observe Daylight Savings Time

Analysis

Field Name Type Definition
dpv_match_code varchar(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.
(eg. 1600 Amphitheatre Pkwy Mountain View, CA)
N — Not Confirmed; address could not be DPV confirmed as deliverable. (only returned as part of the XML response)
S — Confirmed By Dropping Secondary; address was DPV confirmed by dropping secondary info (apartment, suite, etc).
(eg. 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).
(eg. 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 addon code, or the address has already been determined to be Not Deliverable. (only returned as part of the XML response)
dpv_footnotes varchar(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
A1 — ZIP+4 not matched; address is invalid (city/state/zip + street don't match)
BB — ZIP+4 matched; Confirmed entire address; address is valid
CC — Confirmed address by dropping secondary (apartment, suite, etc.) information
F1 — Matched to military address
G1 — Matched to general delivery address
M1 — Primary number (e.g. house number) is missing
M3 — Primary number (e.g. house number) is invalid
N1 — Confirmed with missing secondary information; address is valid but it also needs a secondary number (apartment, suite, etc.)
P1 — PO, RR, or HC box number is missing
P3 — PO, RR, or HC box number is invalid
RR — Confirmed address with private mailbox (PMB) info
R1 — Confirmed address without private mailbox (PMB) info
U1 — Matched a unique ZIP code

Here are some examples:
  • AABB - zip,state,city,street and primary number match
  • AAM1 - zip,state,city,street match but the primary number is missing
  • AAM3 - zip,state,city,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_cmra varchar(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 not submitted for CMRA verification
dpv_vacant varchar(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 being marked vacant.

Y — Address is vacant
N — Address is not vacant
[blank] — Address was not submitted for vacancy verification
active varchar(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_match char(5) Early warning system flag; a positive results 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
footnotes varchar(12) Indicates which changes were made to the input address. Footnotes are delimited by a # character. See the footnotes table below for details.
lacslink_code varchar(2) The reason for the LACSLink indication that was given (below).

A — Match: Address provided. LACSLink record match, 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 is 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 matched after dropping the secondary number from input.
[blank] — No LACSLink lookup attempted.
lacslink_indicator varchar(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 to 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 to a master file record, but the input address has 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_match varchar(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 provide
false — There was no SuiteLink match

Footnotes

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.)

Value Definition Details
A# Corrected ZIP code The 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 ZIPCode field.
(eg. 4800 Fairmount Ave Kansas City MO 64112)
B# Fixed city/state spelling The spelling of the city name and/or state abbreviation in the submitted address was found to be different than the standard spellings. The standard spelling of the city name and state abbreviations are shown in the City and State fields.
(eg. 198 Fowler Dr Bowdon, BA 30108)
C# Invalid city/ state/ZIP The ZIP Code in the submitted address could not be found because a valid city, state, nor valid 5-digit ZIP Code was present. SmartyStreets recommends that the customer check the accuracy of the submitted address.
(eg. 106 Fowler Dr Bowdon, BA 30108)
D# No ZIP+4 assigned This 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.
(eg. 2957 N Oakdale Ave Tampa FL 33602)
E# Same ZIP for multiple Multiple records were returned, but each shares the same 5-digit ZIP Code.
(eg. 1229 Diana Ln Santa Barbara CA 93103)
F# Address not found The address, exactly as submitted, could not be found in the city, state, or ZIP Code provided. Many factors contribute to this: primary number is missing, street missing or even that the street is too horribly misspelled to understand.
(eg. 2600 Rafe Lane Jackson MS 39201 or 100 Beverly Hills, CA)
G# Used firm data Information 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.
(eg. 14315 50th Pl N First Union Plymouth, MN 55446)
H# Missing secondary number ZIP+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).
(eg. 109 Wimbledon Sq Suite E Chesapeake, VA 23320)
I# Insufficient/ incorrect address data More 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 sides of the street.
(eg. 8159 119th Ave W Parrish FL 34219)
J# Dual address The input contained two addresses. For example: 123 MAIN ST PO BOX 99.
(eg. PO Box 38606 30th Street Train Station Philadelphia PA 19104)
K# Cardinal rule match The cardinal direction (North, South, East, West) was changed in order to obtain a match. While the output address is valid, it may not be the intended address, so be aware.
(eg. 315 W Cesar Chavez St Austin TX)
L# Changed address component An address component (i.e., directional or suffix only) was added, changed, or deleted in order to achieve a match.
(eg. 173 Broadway Salt Lake UT 84101)
LL#
or
LI#
Flagged address for LACSLink The input address matched to a record that was LACS-indicated, and that it 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 spelling The spelling of the street name was changed in order to achieve a match.
(eg. 3308 Fountainviuw Monsey NY)
N# Fixed abbreviations The delivery address was standardized. For example, if STREET was in the delivery address, SmartyStreets will return ST as its standard spelling.
(eg. 2438 Brown Ave Knoxville TN 37917)
O# Multiple ZIP+4; lowest used More than one ZIP+4 Code was found to satisfy the address as submitted. The lowest ZIP+4 addon may be used to break the tie between the records.
(eg. RR 2 Box 132 Wolf Summit WV 26426)
P# Better address exists The 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.
(eg. 131 Stone Farm Lebanon NH 03766)
Q# Unique ZIP match Match to an address with a unique ZIP Code.
(eg. 645 Swick Hill Street Charlotte NC 28263)
R# No match; EWS: Match soon The delivery address is matchable, but the Early Warning System file indicates that an exact match will be available soon.
S# Bad secondary address The 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.
(eg. 8100 Highwood Dr # 45 Bloomington MN 55438)
T# Multiple response due to magnet street syndrome The 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.
(eg. 84 Green St Northampton MA)
U# Unofficial post office name The 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.
(eg. 9894 Bissonnet St #723 Sharpstown TX 77036)
V# Unverifiable city / state The 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 city and state in the submitted address.
(eg. 173 Broadway Salt Lake UT 84101)
W# Invalid delivery address The 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 use of a PO Box, General Delivery, or Postmaster for delivery within this ZIP Code.
X# Unique ZIP code Default match inside a unique ZIP Code.
(eg. 609 Pheasant Ridge Road Wayne PA 19088)
Y# Military match Match made to a record with a military ZIP Code.
(eg. PSC 10 Box 1324 APO AE 09142)
Z# Matched with ZIPMOVE The ZIPMOVE product shows which ZIP+4 records have moved from one ZIP Code to another. If an input address matches to a ZIP+4 record which the ZIPMOVE product indicates as having moved, the search is performed again in the new ZIP Code.
(eg. 2600 Tarawa Ct Suite 200 Norfolk VA 23521)

XML usage

While we prefer JSON for it's flexibility and ease of use, our API will still accept and return XML data. Here's a simple example:

curl -v -X POST 'https://api.smartystreets.com/street-address?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE& -H 'Content-Type: application/xml' -H 'Accept: application/xml' --data-binary '
<request>
    <address>
        <addressee>Apple Inc</addressee>
        <street>1 infinite loop</street>
        <street2>po box 42</street2>
        <city>cupertino</city>
        <state>CA</state>
        <zipcode>84014</zipcode>
        <candidates>10</candidates>
    </address>
    <address>
        <street>1600 Pennsylvania ave</street>
        <zipcode>20500</zipcode>
        <candidates>10</candidates>
    </address>
    <address>
        <street>123 main st. 12345</street>
    </address>
</request>'
					

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