Address Lookup

The Address Lookup API allows you to verify and validate US addresses. You can provide either a freeform full address or separate address components (street, apt/suite/other, city, state, zipcode) to verify if they form a valid US address. When using address components, the state field is required.

The address lookup model

The address lookup model contains all the information about address verification results, including the original request details, lookup status, accuracy level, and detailed address components.

Address Lookup Properties

Name
original_lookup_request
Type
OriginalLookupRequest
Description
The original address details provided in the lookup request.
Name
lookup_index
Type
integer
Description
The index of the lookup request in a bulk operation.
Name
address_line1
Type
string
Description
The address line 1 of the verified address.
Name
address_line2
Type
string
Description
The address line 2 of the verified address.
Name
lookup_status
Type
string
Description
The status of the lookup: ADDRESS_FOUND, ADDRESS_PARTIALLY_FOUND, or ADDRESS_NOT_FOUND.
Name
address_accuracy_level
Type
string
Description
The accuracy level of the match: ROOFTOP, ZIP_PLUS4, ZIP5, STATE, or NOT_FOUND.
Name
address_breakdown
Type
AddressBreakdown
Description
Detailed breakdown of address components including street details, city, state, and ZIP code.
Name
address_additional_info
Type
AddressAdditionalInfo
Description
Additional information about the address.
Name
address_delivery_info
Type
AddressDeliveryInfo
Description
USPS delivery point validation details and indicators.

OriginalLookupRequest

Name
full_address
Type
string
Description
Freeform full US address.
Name
street_address
Type
string
Description
The street line of the address.
Name
apt_suite_other
Type
string
Description
The apartment, suite or space number.
Name
city
Type
string
Description
Name of the city.
Name
state
Type
string
Description
The two-letter abbreviation or full name of US state.
Name
zip_code
Type
string
Description
The ZIP code.
Name
country
Type
string
Description
The two or three letter abbreviation. Only US/USA is supported.

AddressBreakdown

Name
primary_no
Type
string
Description
The primary street number.
Name
street_name
Type
string
Description
The name of the street.
Name
street_suffix_abbrev
Type
string
Description
The abbreviated street suffix.
Name
secondary_no
Type
string
Description
The secondary number (apartment, suite, etc.).
Name
secondary_abbrev
Type
string
Description
The abbreviated secondary designator.
Name
city_name
Type
string
Description
Official city name.
Name
preferred_city_name
Type
string
Description
Preferred name for the city.
Name
state
Type
string
Description
State abbreviation.
Name
zip_code
Type
string
Description
The ZIP code.
Name
zip_add_on_no
Type
string
Description
The ZIP+4 add-on number.
Name
county_name
Type
string
Description
Name of the county.

AddressAdditionalInfo

Name
record_type_code
Type
string
Description
The type code for the address record.
Name
carrier_route_id
Type
string
Description
The carrier route identifier.
Name
county_no
Type
string
Description
The county number.
Name
congressional_dist_no
Type
string
Description
The congressional district number.

AddressDeliveryInfo

Name
dpv_confirmation_indicator
Type
string
Description
Delivery Point Validation confirmation indicator.
Name
dpv_cmra_indicator
Type
string
Description
Commercial Mail Receiving Agency indicator.
Name
dpv_door_not_accessible_indicator
Type
string
Description
Indicates if the door is not accessible.
Name
dpv_drop_indicator
Type
string
Description
Drop indicator for delivery point.
Name
dpv_false_positive_indicator
Type
string
Description
False positive indicator for delivery point validation.
Name
dpv_footnotes
Type
string
Description
Additional footnotes for delivery point validation.
Name
dpv_no_stats_indicator
Type
string
Description
No statistics indicator.
Name
dpv_no_stats_reason_code
Type
string
Description
Reason code for no statistics.
Name
dpv_no_secure_location
Type
string
Description
Indicates if there is no secure location for delivery.
Name
dpv_pbsa_indicator
Type
string
Description
PBSA (Post Office Box Street Address) indicator.
Name
dpv_vacant_indicator
Type
string
Description
Indicates if the address is vacant.
Name
residential_delivery_indicator
Type
string
Description
Indicates if this is a residential delivery address.
Name
building_or_firm_name
Type
string
Description
Name of the building or firm at this address.

GET/v1/addresses/lookup

Lookup single address

This endpoint verifies if the provided address is a valid US address. You can provide either a freeform full address or separate address components.

Optional attributes

Name
full_address
Type
string
Description
Freeform full US address.
Name
street_address
Type
string
Description
The street line of the address.
Name
apt_suite_other
Type
string
Description
The apartment, suite or space number.
Name
city
Type
string
Description
Name of the city.
Name
state
Type
string
Description
The two-letter abbreviation or full name of US state.
Name
zip_code
Type
string
Description
The ZIP code.
Name
country
Type
string
Description
The 2 or 3 digit country code. Only US/USA is supported.

Request

GET

/v1/addresses/lookup

curl -G https://us-address.addressfully.com/address-lookup/v1/addresses/lookup \
    -H "Authorization: Bearer {api_key}" \
    -d street_address="1250 Prospect St" \
    -d apt_suite_other="" \
    -d city="La Jolla" \
    -d state="CA" \
    -d zip_code="92037" \
    -d country="US"

Response

{
    "original_lookup_request": {
        "full_address": "",
        "street_address": "1250 Prospect St",
        "apt_suite_other": "",
        "city": "La Jolla",
        "state": "CA",
        "zip_code": "92037",
        "country": "US"
    },
    "lookup_index": 0,
    "address_line1": "1250 PROSPECT ST ",
    "address_line2": "LA JOLLA, CA 92037-3680",
    "lookup_status": "ADDRESS_FOUND",
    "address_accuracy_level": "ROOFTOP",
    "address_breakdown": {
        "primary_no": "1250",
        "street_name": "PROSPECT",
        "street_suffix_abbrev": "ST",
        "secondary_no": "",
        "secondary_abbrev": "",
        "city_name": "LA JOLLA",
        "preferred_city_name": "LA JOLLA",
        "state": "CA",
        "zip_code": "92037",
        "zip_add_on_no": "3680",
        "county_name": "SAN DIEGO"
    },
        "address_additional_info": {
        "record_type_code": "H",
        "carrier_route_id": "C013",
        "county_no": "073",
        "congressional_dist_no": "50"
    },
    "address_delivery_info": {
        "dpv_confirmation_indicator": "",
        "dpv_cmra_indicator": "",
        "dpv_door_not_accessible_indicator": "",
        "dpv_drop_indicator": "",
        "dpv_false_positive_indicator": "",
        "dpv_footnotes": "",
        "dpv_no_stats_indicator": "",
        "dpv_no_stats_reason_code": "",
        "dpv_no_secure_location": "",
        "dpv_pbsa_indicator": "",
        "dpv_vacant_indicator": "",
        "residential_delivery_indicator": "",
        "building_or_firm_name": ""
    }
}