Verifies and validates US street addresses against the USPS database, returning standardized components, deliverability status, and up to 55 metadata points including ZIP9 geocodes. Supports both single-address GET requests and batch POST requests of up to 100 addresses per call.
openapi: 3.0.1
info:
title: Smarty US Street Address Verifier
version: '5.3'
description: ''
contact:
url: 'https://www.smarty.com/contact/support'
email: [email protected]
name: Smarty Support
termsOfService: 'https://www.smarty.com/legal/terms-of-service'
license:
url: 'https://www.smarty.com/legal/terms-of-service'
name: Smarty License
servers:
- url: us-street.api.smarty.com
externalDocs:
description: "Extensive documentation for the US Street API"
url: https://www.smarty.com/docs/cloud/us-street-api
paths:
/street-address:
get:
summary: Single Address Validation
tags:
- street-address
security:
- auth-id: [ ]
auth-token: [ ]
- embedded-key: [ ]
operationId: get-street-address
responses:
'200':
$ref: '#/components/responses/SuccessfulResponse'
'400':
description: 'Bad Request (Malformed Payload): A GET request lacked a street field, or the request body of a POST request contained malformed JSON. (example: submitting an integer value in the ZIP Code field when a string is expected)'
'401':
description: 'Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.'
'402':
description: 'Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.'
'429':
description: 'Too Many Requests: When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. If you use embedded key authentication, you can avoid this error by adding your IP address as an authorized host for the embedded key in question.'
description: |
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 (line breaks added for readability):
```
curl -v 'https://us-street.api.smarty.com/street-address?
auth-id=YOUR+AUTH-ID+HERE&
auth-token=YOUR+AUTH-TOKEN+HERE&
street=1600+amphitheatre+pkwy&
city=mountain+view&
state=CA&
candidates=10'
```
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.
parameters:
- schema:
type: string
example: 'Content-Type: application/json'
in: header
name: Content-Type
description: 'The 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.'
required: true
- schema:
type: string
example: 'Host: us-street.api.smarty.com'
in: header
name: Host
description: 'The Host request header field specifies the internet host of the resource being requested. Optionally, it can also specify a non-default port number.'
required: true
- $ref: '#/components/parameters/input_id'
- $ref: '#/components/parameters/street'
- $ref: '#/components/parameters/street2'
- $ref: '#/components/parameters/secondary'
- $ref: '#/components/parameters/city'
- $ref: '#/components/parameters/state'
- $ref: '#/components/parameters/zipcode'
- $ref: '#/components/parameters/lastline'
- $ref: '#/components/parameters/addressee'
- $ref: '#/components/parameters/urbanization'
- $ref: '#/components/parameters/candidates'
- $ref: '#/components/parameters/match'
- $ref: '#/components/parameters/format'
- $ref: '#/components/parameters/county_source'
- $ref: '#/components/parameters/features'
post:
summary: Multiple Address Validation
tags:
- street-address
operationId: post-street-address
security:
- auth-id: [ ]
auth-token: [ ]
- embedded-key: [ ]
responses:
'200':
$ref: '#/components/responses/SuccessfulResponse'
'400':
description: 'Bad Request (Malformed Payload): A GET request lacked a street field, or the request body of a POST request contained malformed JSON. (example: submitting an integer value in the ZIP Code field when a string is expected)'
'401':
description: 'Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.'
'402':
description: 'Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.'
'413':
description: 'Request Entity too large: The maxmimum size for a request body to this API is 32K (32,768 bytes).'
'422':
description: 'Unprocessable entity: A POST request lacked a street field.'
'429':
description: 'Too Many Requests: When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. If you use embedded key authentication, you can avoid this error by adding your IP address as an authorized host for the embedded key in question.'
description: |
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 (line breaks added for readability):
```bash
curl -v 'https://us-street.api.smarty.com/street-address?
auth-id=YOUR+AUTH-ID+HERE&
auth-token=YOUR+AUTH-TOKEN+HERE&'
-H "Content-Type: application/json; charset=utf-8"
--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
}
]'
```
parameters:
- schema:
type: string
example: 'Content-Type: application/json'
in: header
name: Content-Type
required: true
description: 'The 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.'
- schema:
type: string
example: 'Host: us-street.api.smarty.com'
in: header
required: true
name: Host
description: 'The Host request header field specifies the internet host of the resource being requested. Optionally, it can also specify a non-default port number.'
requestBody:
$ref: '#/components/requestBodies/MultipleAddressRequest'
parameters: [ ]
components:
parameters:
input_id:
name: input_id
in: query
description: '**Input ID** *Example: 867-5309* A unique identifier for this address used in your application; this field will be copied to the output'
schema:
type: string
maxLength: 36
street:
name: street
in: query
description: '**Street** *Example: 1600+amphitheatre+pkwy* The street line of the address, or the entire address(''freeform'' input).'
schema:
type: string
maxLength: 50
street2:
name: street2
in: query
description: '**Street2** *Example: Leave it on the front porch* Any extra address information.'
schema:
type: string
secondary:
name: secondary
in: query
description: '**Secondary** *Example: Apt 52* Apartment, suite, or office number.'
schema:
type: string
city:
name: city
in: query
description: '**City** *Example: Provo* The city name.'
schema:
type: string
state:
name: state
in: query
description: '**State** *Example: UT* State name or two-letter abbreviation.'
schema:
type: string
zipcode:
name: zipcode
in: query
description: '**Zip code** *Example: 84604* The ZIP Code.'
schema:
type: string
lastline:
name: lastline
in: query
description: '**Last Line** *Example: Provo, UT 84604* City, state, and ZIP Code combined.'
schema:
type: string
addressee:
name: addressee
in: query
description: '**Addressee** *Example: John Doe* The name of the recipient, firm, or company at this address.'
schema:
type: string
urbanization:
name: urbanization
in: query
description: '**Urbanization** Only used with Puerto Rico.'
schema:
type: string
candidates:
name: candidates
in: query
description: '**Candidates** *Example: 1* The maximum number of valid addresses returned when the input is ambiguous (Max Value: 10).'
schema:
type: string
match:
name: match
in: query
description: '**Match Type** *Example: invalid* The match output strategy to be employted for this lookup. Valid values are: **strict**: The API will ONLY return candidates that are valid USPS addresses. **range**: The API will return candidates that are valid USPS addresses, as well as invalid addresses with primary numbers that fall within a valid range for the street. **invalid**: The API will return a single candidate for every properly submitted address, even if invalid or ambiguous.'
schema:
type: string
format:
name: format
in: query
description: 'The output format to be employed for this lookup, with an appropriate product subscription. Valid values are: default The API will return the address in the default format. project-usa The API will return the address in Project US@ format.'
schema:
type: string
county_source:
name: county_source
in: query
description: 'The authoritative source to be used for the county information of the address. Valid values are: postal The API will return county information based on the postal delivery information of the address. This is the default option. geographic The API will return county information based on the physical location of the address.'
schema:
type: string
features:
name: features
in: query
description: 'Component Analysis is available in the US Address Verification 42-day Free Trial and certain custom plans. If you have a subscription that allows for component analysis details, to return the component analysis details include the features parameters as features=components-analysis.'
schema:
type: string
schemas:
Root:
title: Response Component
type: object
description: Object found in the response list to the request
properties:
input_id:
type: string
maxLength: 36
description: Any unique identifier that you use to reference the input address; the output will be identical to the input.
input_index:
type: integer
description: |-
The order in which this address was submitted with the others
(0 if alone)
candidate_index:
type: integer
description: |-
An 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.)
addressee:
type: string
description: 'The name of the person or company at this address. This value is taken directly from the addressee input field. Very rarely, this field might be filled automatically based on the USPS address record.'
maxLength: 64
delivery_line_1:
type: string
description: |-
Contains the first delivery line (usually the street address). This can include any of the following:
- urbanization (Puerto Rico only)
- primary number
- street predirection
- street name
- street suffix
- street postdirection
- secondary designator
- secondary number
- extra secondary designator
- extra secondary number
- PMB designator
- PMB number
maxLength: 64
delivery_line_2:
type: string
description: 'The second delivery line (if needed). It is common for this field to remain empty, but it may contain a private mailbox number.'
maxLength: 64
last_line:
type: string
description: 'City, state, and ZIP Code combined'
maxLength: 64
delivery_point_barcode:
type: string
description: '12-digit POSTNET™ barcode; consists of 5-digit ZIP Code, 4-digit add-on code, 2-digit delivery point, and 1-digit check digit.'
maxLength: 12
smarty_key:
type: string
description: "Smarty's unique identifier for an address. This identifier will only be displayed when an address is submitted with the match parameter set to enhanced, with an appropriate product subscription."
maxLength: 10
components:
$ref: '#/components/schemas/Components'
metadata:
$ref: '#/components/schemas/Metadata'
analysis:
$ref: '#/components/schemas/Analysis'
component-analysis:
$ref: '#/components/schemas/Component-Analysis'
Components:
title: Components
type: object
description: Object representing the different components of a verified address
properties:
urbanization:
type: string
maxLength: 64
description: 'The neighborhood, or city subdivision; used with Puerto Rican addresses'
primary_number:
type: string
description: 'The house, PO Box, or building number'
maxLength: 30
street_name:
type: string
description: The name of the street
maxLength: 64
street_predirection:
type: string
maxLength: 16
description: 'Directional information before a street name (N, SW, etc.)'
street_postdirection:
type: string
description: 'Directional information after a street name (N, SW, etc.)'
maxLength: 16
street_suffix:
type: string
description: 'Abbreviated value describing the street (St, Ave, Blvd, etc.)'
maxLength: 16
secondary_number:
type: string
description: 'Apartment or suite number, if any'
maxLength: 32
secondary_designator:
type: string
description: 'Describes location within a complex/building (Ste, Apt, etc.)'
maxLength: 16
extra_secondary_number:
type: string
description: |-
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")
maxLength: 32
extra_secondary_designator:
type: string
description: |-
Description of the location type within a campus
(e.g., Bldg, Unit, Lot, etc.)
maxLength: 16
pmb_designator:
type: string
description: 'The private mailbox unit designator, assigned by a CMRA'
maxLength: 16
pmb_number:
type: string
description: 'The private mailbox number, assigned by a CMRA'
maxLength: 16
city_name:
type: string
description: 'The USPS-preferred city name for this particular address, or an acceptable alternate if provided by the user'
maxLength: 64
default_city_name:
type: string
description: The default city name for this 5-digit ZIP Code
maxLength: 64
state_abbreviation:
type: string
description: The two-letter state abbreviation
maxLength: 2
zipcode:
type: string
description: The 5-digit ZIP Code
maxLength: 5
plus4_code:
type: string
description: The 4-digit add-on code (more specific than 5-digit ZIP)
maxLength: 4
delivery_point:
type: string
description: '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).'
maxLength: 2
delivery_point_check_digit:
type: string
description: 'Correction character, or check digit, for the 11-digit barcode'
maxLength: 1
Metadata:
title: Metadata
type: object
properties:
record_type:
type: string
maxLength: 1
description: |-
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.
(e.g., Julie Julia 11300 Center Ave Gilroy CA 95020-9257)
G — General Delivery; for mail to be held at local post offices.
(e.g., General Delivery Provo UT 84601)
H — High-rise; address contains apartment or building sub-units.
(e.g., 1600 Pennsylvania Ave SE Washington DC 20003-3228)
P — Post Office box
(e.g., PO Box 4735 Tulsa OK 74159-0735)
R — Rural Route or Highway Contract; may have box number ranges.
(e.g., RR 2 Box 4560 Anasco PR 00610-9393)
S — Street; address contains a valid primary number range.
(e.g., 16990 Monterey Rd Lake Elsinore CA 92530-7529)
[blank] — No record type because address did not make a valid DPV match
zip_type:
type: string
maxLength: 32
description: |-
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 US 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 a PO Box ZIP Code and is assigned to a collection of Post Office Boxes.
Standard — The ZIP Code does not pertain to any of the above categories.
county_fips:
type: string
maxLength: 5
description: 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:
type: string
maxLength: 5
description: The name of the county in which the address is located
ews_match:
type: string
maxLength: 5
description: |-
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.
carrier_route:
type: string
maxLength: 4
description: |-
The postal carrier route for the address. Consists of a one-letter prefix followed by a three-digit route designator.
(e.g., C007, R123)
C — Carrier Route (commonly termed "City Route")
R — Rural Route
H — Highway Contract Route
B — Post Office Box Section
G — General Delivery Unit
Routes C770 through C779 pertain to PO Box Street Addresses.
congressional_district:
type: string
maxLength: 2
description: '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:
type: string
maxLength: 1
description: |-
Indicates whether the address is the "default" address for a building; for example, the main lobby
Y — Yes
N — No
rdi:
type: string
maxLength: 12
description: |-
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 or we don't have enough information to ascertain RDI status. The Bulk Address Validation Tool translates 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_sequence:
type: string
maxLength: 4
description: eLOT (Enhanced Line of Travel) 4-digit sequence number
elot_sort:
type: string
maxLength: 4
description: |-
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:
type: number
description: '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.'
longitude:
type: number
description: '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.'
coordinate_license:
type: integer
description: The license ID for the geographic coordinate returned. See the licensing table below for more details.
precision:
type: string
maxLength: 18
description: |-
Indicates the precision of the latitude and longitude values.
Unknown — Coordinates not known. Reasons could include: address is invalid, military address (APO or FPO), lat/lon coordinates not available.
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 with the basic subscription)
Street — Accurate to a position along the street proportional to the house/building number.
Parcel — Accurate to the centroid of a property parcel. Requires the US Rooftop Geocoding subscription.
Rooftop — Accurate to the rooftop of a structure for this address. Requires the US Rooftop Geocoding subscription.
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_zone:
type: string
maxLength: 48
description: |-
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_offset:
type: number
description: |-
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
dst:
type: string
maxLength: 5
description: |-
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.
description: Object representing the different metadata of a verified address
Analysis:
title: Analysis
type: object
properties:
dpv_match_code:
type: string
maxLength: 1
description: |-
Status of the Delivery Point Validation (DPV). This indicates whether or not the address is present in the USPS data.
Y — Confirmed; entire address is present in the USPS data. (To be certain the address is actually deliverable, verify that the dpv_vacant field has a value of N. You may also want to verify that the dpv_no_stat field has a value of N. However, the USPS is often several months behind in updating this data point, so only rely on the dpv_no_stat data if you are fully aware of its weaknesses and limitations.)
(e.g., 1600 Amphitheatre Pkwy Mountain View, CA)
N — Not confirmed; address is not present in the USPS data.
S — Confirmed by ignoring secondary info; the main address is present in the USPS data, but the submitted secondary information (apartment, suite, etc.) was not recognized.
(e.g., 62 Ea Darden Dr Apt 298 Anniston, AL)
D — Confirmed but missing secondary info; the main address is present in the USPS data, but it is missing secondary information (apartment, suite, etc.).
(e.g., 122 Mast Rd Lee, NH)
[blank or null] — The address is not present in the USPS database.
dpv_footnotes:
type: string
maxLength: 32
description: |-
Information related to the delivery point validation of this address. All these footnotes have a length of 2 characters, and there may be up to 14 footnotes.
AA — Street name, city, state, and ZIP are all valid.
(e.g., 2335 S State St Ste 300 Provo UT)
A1 — Address not present in USPS data.
(e.g., 3214 N University Ave New York NY)
BB — Entire address is valid.
(e.g., 2335 S State St Ste 300 Provo UT)
CC — The submitted secondary information (apartment, suite, etc.) was not recognized. Secondary number is NOT REQUIRED for delivery.
(e.g., 3331 Erie Ave Apt 2 Cincinnati OH 45208)
C1 — The submitted secondary information (apartment, suite, etc.) was not recognized. Secondary number IS REQUIRED for delivery.
(e.g., 2335 S State St Ste 500 Provo UT)
F1 — Military or diplomatic address
(e.g., Unit 2050 Box 4190 APO AP 96278)
G1 — General delivery address
(e.g., General Delivery Provo UT 84601)
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 — Address is missing secondary information (apartment, suite, etc.).
(e.g., 2335 S State St Provo UT)
PB — PO Box street style address.
(e.g., 555 S B B King Blvd Unit 1 Memphis TN 38103)
P1 — PO, RR, or HC box number is missing.
(e.g., Dept 126 Denver CO 802910126)
P3 — PO, RR, or HC box number is invalid.
(e.g., PO BOX 60780 FAIRBANKS AK 99706)
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)
R7 — Confirmed as a valid address that doesn't currently receive US Postal Service street delivery.
(e.g., 6D Cruz Bay St John VI 00830)
TA — Primary number was matched by dropping trailing alpha.
(e.g., 4-C PENINSULA CTR RANCHO PALOS VERDES CA 90274)
U1 — Address has a "unique" ZIP Code.
(e.g., 100 North Happy Street 12345)
Here are some common combinations:
AABB - ZIP, state, city, street name, and primary number match.
AABBCC - ZIP, state, city, street name, and primary number match, but secondary does not. A secondary is NOT required for delivery.
AAC1 - ZIP, state, city, street name, and primary number match, but secondary does not. A secondary is required for delivery.
AAM1 - ZIP, state, city, and street name match, but the primary number is missing.
AAM3 - ZIP, state, city, and street name match, but the primary number is invalid.
AAN1 - ZIP, state, city, street name, and primary number match, but there is secondary information such as apartment or suite that would be helpful.
AABBR1 - ZIP, state, city, street name, and primary number match. Address confirmed without private mailbox (PMB) info.
dpv_cmra:
type: string
maxLength: 1
description: |-
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_vacant:
type: string
maxLength: 1
description: |-
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.
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smarty/refs/heads/main/openapi/smarty-us-street-address-api-openapi.yml