US Address Enrichment API

This page describes how to retrieve data from various different datasets using the Smarty US Address Enrichment API.

Contents

1. HTTP request
   1. URL composition
   2. Request methods
   3. Headers
   4. Input Fields
   5. Available datasets
   6. Address search
   7. Attribute groups
2. HTTP response
   1. Results
3. Supplementary materials
   1. Basic use cases
   2. SSL/TLS information
   3. Try the Address Enrichment API

HTTP request: URL composition

Proper URL construction is required for all API requests. Here are some example URLs:

https://us-enrichment.api.smarty.com/lookup/1000000/property/principal?auth-id=12345&auth-token=abcdef

https://us-enrichment.api.smarty.com/lookup/1000000/geo-reference?auth-id=12345&auth-token=abcdef

https://us-enrichment.api.smarty.com/lookup/1000000/secondary?auth-id=12345&auth-token=abcdef

https://us-enrichment.api.smarty.com/lookup/search/secondary?auth-id=12345&auth-token=abcdef&street=1400+Sandhill+Rd+Orem+UT
	

Here is a more granular examination of the examples above:

URL components	Values	Notes
Scheme	https	NOTE: Non-secure http requests are not supported
Hostname	us-enrichment.api.smarty.com
Path	/lookup
SmartyKey or search	/1000000 /search	The unique id associated with the address you are looking for. OR the word search if you are using any input fields for address searching.
Dataset	/property/principal /property/financial /geo-reference /geo-reference/2010 /geo-reference/2020 /secondary /secondary/count	Specify one of the available Datasets
Query string	?auth-id=12345&auth-token=abcdef	Authentication information

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

HTTP request: Supported 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:

• GET (for sending a single input)

HTTP request: Headers

Header	Description	Example
Content-type	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.	Content-type: application/json
ETag	The ETag header provides the ability to check if a record has been updated since the last query. Every query to the API will return an ETag header which represents a hash of the record in the response. This value may be stored and used in subsequent queries for that same record. If the record data has NOT been updated since the last query, it will return a 304 (Not Modified) and the client will not be charged for the query. (The 304 response does not contain a body.) If the record data HAS been updated, the latest version of the record will be returned along with a new ETag value. Important: Only the latest ETag value is valid for each record. This feature is NOT designed to retrieve past record versions. Also note that the ETag value will change if ANY data in the record has been updated, regardless of which attributes are requested using the include and exclude parameters.	ETag: AUHQQBIPBQDAYAA

Input fields

Name	Type	Default value	Description
include	string	(empty)	List of attributes that are allowed to be included in the response. This list can include Group names and Attribute names separated by commas. All values must be lowercase. If the record in the response does not have a value for that attribute, it will not be included in the response.
exclude	string	(empty)	List of attributes that are not allowed to be included in the response. This list can include Group names and Attribute names separated by commas. All values must be lowercase.
Optional Address Search Fields			IMPORTANT: When using any search field, you must specify the word search in place of the SmartyKey in the URL. See examples.
freeform	string	(empty)	A full address.
street	string	(empty)	The street line of the address, or the entire address. You may also need to provide values for other component search fields.
city	string	(empty)	The city name or a city, state, and ZIP Code combined. You may also need to provide values for other component search fields.
state	string	(empty)	The state name or abbreviation. You may also need to provide values for other component search fields.
zipcode	string	(empty)	The ZIP Code. You may also need to provide values for other component search fields.

All input field parameters must be UTF-8 and then URL encoded.

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 code	Response and explanation
200	OK (success!): The response body is a JSON object containing metadata about the results and zero or one addresses from the input provided with the request. See the annotated example below for details. An ETag header value will also be returned which represents a hash of the current record. (See ETag header in the request.)
304	Not modified: The requested ETag header represents the latest data available.
400	Bad request (malformed payload): The request body was blank or otherwise malformed.
401	Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402	Payment required: There is no active subscription for the account associated with the credentials submitted with the request.
413	Request entity too large: The request body was larger than 64 Kilobytes.
422	Unprocessable content: Some parameter values are not correct. Detailed messages will describe the problem.
429	Too many requests: We restrict the number of requests coming from a given source over too short of a time.

Example response - property/principal Dataset

[
	{
		"smarty_key": "4888552154",
		"data_set_name": "property",
		"data_subset_name": "principal",
		"attributes": {
			"1st_floor_sqft": "2302",
			"2nd_floor_sqft": "0",
			"acres": "0.3289945",
			"address_info_privacy": "",
			"air_conditioner": "yes",
			"arbor_pergola": "unknown",
			"assessed_improvement_percent": "0.00",
			"assessed_improvement_value": "0",
			"assessed_land_value": "0",
			"assessed_value": "399960",
			"assessor_last_update": "2023-01-05",
			"assessor_taxroll_update": "2022-01-01",
			"attic_area": "405",
			...
		}
	}
]

Example response - property/financial Dataset

[
	{
		"smarty_key": "9856148841",
		"data_set_name": "property",
		"data_subset_name": "financial",
		"attributes": {
			"assessor_taxroll_update": "2022-01-01",
			"attic_area": "405",
			"recorder": [
				{
					"recording_date": "2022-01-01",
					"instrument_date": "2022-01-01",
					"sale_price": "1",
					...
				},
				{
					"recording_date": "2023-01-01",
					"instrument_date": "2023-01-01",
					"sale_price": "2",
					...
				}
			],
			...
		}
	}
]

Example response - Geo-reference dataset

[
	{
		"smarty_key": "1601354568",
		"data_set_name": "geo-reference",
		"data_set_version": "census-2020",
		"attributes": {
			"census_block": {
				"accuracy": "block",
				"geoid": "530050109014000"
			},
			"census_county_division": {
				"accuracy": "exact",
				"code": "5300592768",
				"name": "Richland-Kennewick"
			},
			"census_tract": {
				"code": "0109.01"
			},
			"core_based_stat_area": {
				"code": "28420",
				"name": "Kennewick-Richland, WA"
			},
			"place": {
				"accuracy": "exact",
				"code": "5335275",
				"name": "Kennewick",
				"type": "incorporated"
			}
		}
	}
]

Example response - Secondary dataset

[
	{
		"smarty_key": "1106658436",
		"root_address": {
			"secondary_count": 3,
			"smarty_key": "1106658436",
			"primary_number": "11401",
			"street_name": "Dr Martin Luther King Jr",
			"street_suffix": "St",
			"street_postdirection": "N",
			"city_name": "Saint Petersburg",
			"state_abbreviation": "FL",
			"zipcode": "33716",
			"plus4_code": "2345"
		},
		"aliases": [
			{
				"smarty_key": "1106658436",
				"primary_number": "11401",
				"street_name": "9th",
				"street_suffix": "St",
				"street_postdirection": "N",
				"city_name": "Saint Petersburg",
				"state_abbreviation": "FL",
				"zipcode": "33716",
				"plus4_code": "2345"
			}
		],
		"secondaries": [
			{
				"smarty_key": "347247266",
				"secondary_designator": "Apt",
				"secondary_number": "101",
				"plus4_code": "2310"
			},
			{
				"smarty_key": "1301723551",
				"secondary_designator": "Apt",
				"secondary_number": "102",
				"plus4_code": "2310"
			},
			{
				"smarty_key": "538303441",
				"secondary_designator": "Apt",
				"secondary_number": "103",
				"plus4_code": "2313"
			}
		]
	}
]

Example response - Secondary/count dataset

[
	{
		"smarty_key": "1166392406",
		"count": 12
	}
]

Data sets

See URL composition for all available options.

• US Property Principal Data (property/principal)
  • Contains all property data attributes including tax assessor and recorder data
  • Recorder data will be last available financial transaction for the property
• US Property Financial Data (property/financial)
  • Dataset that contains historical financial data attributes pertaining to the property and property owner.
• US GeoReference Data (geo-reference, geo-reference/2010, geo-reference/2020)
  • The GeoReference Data product provides useful geographic data for geocoded addresses, such as census block id.
  • Request legacy data, such as the 2010 and 2020 census, by specifying a data subset of 2010 or 2020.
    For example: To return 2010 census data, specify geo-reference/2010.
  • To request the latest census information available, simply specify geo-reference with no trailing subset.
  • The census version will be returned in the data_set_version property in the response.

  Category	Data element	Definition
  census_block		An id of up to 15 characters that identifies a geographical area for statistical analysis.
  	accuracy	Represents the accuracy of the geocode associated with the SmartyKey which was used to find the block. Values are block, tract, or county.
  	geoid	The census geoid can have different meanings based on the accuracy field. If geocode accuracy is parcel or rooftop, the id is the 15 character block id. If geocode accuracy is zip9, the id is the census tract id. (first 11 digits of block id) If geocode accuracy is less than zip9, the id is the county FIPS. (first 5 digits of block id)
  census_county_division		The county subdivision identifier and name (equivalent to townships).
  	accuracy	Represents the accuracy of the geocode associated with the SmartyKey. Less than Zip9 accuracy will be inferred. Otherwise, it will be exact.
  	code	The 10-digit census id code of the CCD.
  	name	The name of the census county division.
  census_tract		Geographic entities within counties (or the statistical equivalent of counties).
  	code	Census tracts within a county are identified by a 4-digit basic code between 0001 and 9999, and may have a 2-digit suffix ranging from .01 to .98; (e.g. 6059.02)
  core_based_stat_area		Refers collectively to metropolitan statistical areas and micropolitan statistical areas. CBSAs consist of the county or counties (or equivalent entities) associated with at least one core (urban area) with a population of at least 10,000, plus adjacent counties having a high degree of social and economic integration with the core as measured through commuting ties.
  	code	A 5-digit unique id of the CBSA (e.g. 39340)
  	name	The name of the CBSA (e.g. Provo-Orem, UT)
  place		The Bureau of the Census defines a place as a concentration of population. It consists of a geographical boundary.
  	accuracy	Represents the accuracy of the geocode associated with the SmartyKey. Less than Zip9 accuracy will be inferred. Otherwise, it will be exact.
  	code	A 7-digit code that identifies the place. The first 2 digits identify the state. The last 5 identify the place within the state.
  	name	The name of the place boundary.
  	type	Indicates if the Census Place is incorporated or unincorporated.

• Secondary data (secondary, secondary/count)
  • The secondary data product returns all secondaries and aliases associated with a SmartyKey.
  • The SmartyKey can be that of the root address, any of the aliases, or any of the secondaries. Each will return the same related data.
  • The count subset only returns the number of secondaries associated with the SmartyKey. Detailed data is not returned.

Address searching

To perform an address search instead of providing a SmartyKey, you may use the search input fields. Note that you replace the SmartyKey value with the string search in the URL. You will also need a subscription that allows Address Searching.

Example address search requests:

https://us-enrichment.api.smarty.com/lookup/search/property/principal?auth-id=12345&auth-token=abcdef&freeform=1400+Sandhill+Rd+Orem+UT+84058

https://us-enrichment.api.smarty.com/lookup/search/property/principal?auth-id=12345&auth-token=abcdef&street=1400+Sandhill+Rd&city=Orem+UT+84058

https://us-enrichment.api.smarty.com/lookup/search/geo-reference?auth-id=12345&auth-token=abcdef&street=1400+Sandhill+Rd&city=Orem&state=UT&zipcode=84058
	

This example address search response shows the search result in matched_address. If no match is found, an empty result will be returned similar to when an invalid SmartyKey is provided during a standard lookup. If multiple matches are found because the input was ambiguous, the SmartyKey from the first result will be used.

[
	{
		"smarty_key": "2127882360",
		"data_set_name": "property",
		"data_subset_name": "principal",
		"matched_address": {
			"street": "1400 Sandhill Rd",
			"city": "Orem",
			"state": "UT",
			"zipcode": "84058-7310"
		},
		"attributes": {
			"acres": "7.0159998",
			"air_conditioner": "yes",
			"assessed_value": "14308800"
	}
	}
]

Attribute groups (For US property datasets)

The following attribute groups are supported in the include and exclude input parameters when performing a request for US Property records.

Group name	Description	Attributes included
group_financial	Financial attributes in the Principal Dataset records	assessed_improvement_percent assessed_improvement_value assessed_land_value assessed_value assessor_last_update assessor_taxroll_update code_title_company company_flag contact_city contact_crrt contact_full_address contact_house_number contact_mail_info_format contact_mailing_county contact_mailing_fips contact_post_direction contact_pre_direction contact_state contact_street_name contact_suffix contact_unit_designator contact_value contact_zip contact_zip4 deed_ document_page deed_document_book deed_document_number deed_owner_first_name deed_owner_first_name2 deed_owner_first_name3 deed_owner_first_name4 deed_owner_full_name deed_owner_full_name2 deed_owner_full_name3 deed_owner_full_name4 deed_owner_last_name deed_owner_last_name2 deed_owner_last_name3 deed_owner_last_name4 deed_owner_middle_name deed_owner_middle_name2 deed_owner_middle_name3 deed_owner_middle_name4 deed_owner_suffix deed_owner_suffix2 deed_owner_suffix3 deed_owner_suffix4 deed_sale_date deed_sale_price deed_transaction_id disabled_tax_exemption first_name first_name_2 first_name_3 first_name_4 homeowner_tax_exemption instrument_date interest_rate interest_rate_type_2 last_name last_name_2 last_name_3 last_name_4 lender_address lender_address_2 lender_city lender_city_2 lender_code_2 lender_first_name lender_first_name_2 lender_last_name lender_last_name_2 lender_name lender_name_2 lender_seller_carry_back lender_seller_carry_back_2 lender_state lender_state_2 lender_zip lender_zip_2 lender_zip_extended lender_zip_extended_2 loan_amount market_improvement_percent market_improvement_value market_land_value market_value_year middle_name middle_name_2 middle_name_3 middle_name_4 mortgage_amount_2 mortgage_due_date mortgage_due_date_2 mortgage_interest_type mortgage_lender_code mortgage_start_date mortgage_start_date_2 mortgage_term mortgage_term_2 mortgage_term_type mortgage_term_type_2 mortgage_type mortgage_type_2 mortgate_rate_2 multi_parcel_flag name_title_company other_tax_exemption owner_full_name owner_full_name_2 owner_full_name_3 owner_full_name_4 owner_occupancy_status ownership_transfer_date ownership_transfer_doc_number ownership_transfer_transaction_id ownership_type ownership_type_2 ownership_vesting_relation_code previous_assessed_value prior_sale_amount prior_sale_date sale_amount sale_date sale_price senior_tax_exemption suffix suffix_2 suffix_3 suffix_4 tax_assess_year tax_billed_amount tax_delinquent_year tax_fiscal_year tax_rate_area total_market_value trust_description veteran_tax_exemption widow_tax_exemption
group_location	Location attributes in the Principal Dataset records	block1 block2 carrier_route_code cbsa_code cbsa_name census_block census_block_group census_fips_place_code census_tract city combined_statistical_area congressional_district elevation_feet fips_code geo_quality house_number land_use_code land_use_group land_use_standard latitude legal_description legal_unit longitude lot_1 lot_2 lot_3 metro_division minor_civil_division_code minor_civil_division_name msa_code msa_name neighborhood_code parcel_account_number parcel_map_book parcel_map_page parcel_number_alternate parcel_number_formatted parcel_number_previous parcel_number_year_added parcel_number_year_change parcel_raw_number phase_name post_direction pre_direction property_address_full quarter quarter_quarter range section situs_county situs_state state street_name street_suffix subdivision tax_jurisdiction township tract_number unit_designator unit_value zip_4 zipcode zoning
group_structural	Structural attributes in the Principal Dataset records	1st_floor_sqft 2nd_floor_sqft acres air_conditioner arbor_pergola attic_area attic_flag balcony balcony_area basement_sqft basement_sqft_finished basement_sqft_unfinished bath_house bath_house_sqft bathrooms_partial bathrooms_total bedrooms boat_access boat_house boat_house_sqft boat_lift bonus_room breakfast_nook breezeway building_definition_code building_sqft cabin cabin_sqft canopy canopy_sqft carport carport_sqft cellar central_vacuum community_rec construction_type courtyard courtyard_area deck deck_area depth_linear_footage driveway_sqft driveway_type effective_year_built elevator equestrian_arena escalator exercise_room exterior_walls family_room fence fence_area fire_resistance_code fire_sprinklers_flag fireplace fireplace_number flooring foundation game_room garage garage_sqft gazebo gazebo_sqft golf_course grainery grainery_sqft great_room greenhouse greenhouse_sqft gross_sqft guesthouse guesthouse_sqft handicap_accessibility heat heat_fuel_type hobby_room intercom_system interior_structure kennel kennel_sqft laundry lean_to lean_to_sqft loading_platform loading_platform_sqft lot_sqft media_room milkhouse milkhouse_sqft mobile_home_hookup mud_room number_of_buildings office office_sqft overhead_door parcel_shell_record parking_spaces patio_area plumbing_fixtures_count pole_struct pole_struct_sqft pond pool pool_area poolhouse poolhouse_sqft porch porch_area poultry_house poultry_house_sqft publication_date quonset quonset_sqft roof_cover roof_frame rooms rv_parking safe_room sauna security_alarm sewer_type shed shed_sqft silo silo_sqft sitting_room sound_system sports_court sprinklers stable stable_sqft storage_building storage_building_sqft stories_number storm_shelter storm_shutter structure_style study sunroom tennis_court topography_code unit_count upper_floors_sqft utility utility_building utility_building_sqft utility_sqft view_description water_feature water_service_type wet_bar width_linear_footage wine_cellar year_built

Basic use cases

HTTP GET - SmartyKey valid - Property data exists

Precondition	SmartyKey is valid. Property data exists.
Action	https://us-enrichment.api.smarty.com/lookup/111111/property/principal
Result	All results for specific SmartyKey returned.

HTTP GET - SmartyKey Has No Property Data

Precondition	SmartyKey has no property data
Action	https://us-enrichment.api.smarty.com/lookup/111111/property/principal
Result	Empty results returned.

HTTP GET - Use include and exclude Parameters Containing a Group in Principal Data

Precondition	SmartyKey is valid. Property data exists.
Action	https://us-enrichment.api.smarty.com/lookup/111111/property/principal?include=group_structural&exclude=attic_flag,boat_lift
Result	Available data for that SmartyKey within the attribute group group_structural, excluding the attic_flag and boat_lift attributes.

HTTP GET - SmartyKey valid - Property financial data exists

Precondition	SmartyKey is valid. Property data exists.
Action	https://us-enrichment.api.smarty.com/lookup/111111/property/financial
Result	All results for specific SmartyKey returned.

HTTP GET - Use of ETag Header Where Data Has Not Been Updated

Precondition	SmartyKey is valid. Property data exists. An ETag value from a previous query and the data has not changed.
Action	Header: ETag: AABBCCDD https://us-enrichment.api.smarty.com/lookup/111111/property/financial
Result	HTTP 304 indicating that the data has not changed. There was no charge for the lookup.

HTTP GET - Use of ETag Header Where Data Has Changed

Precondition	SmartyKey is valid. Property data exists. An ETag value from a previous query and the data has changed.
Action	Header: ETag: AABBCCDD https://us-enrichment.api.smarty.com/lookup/111111/property/financial
Result	All results for specific SmartyKey returned. A new ETag value is also returned.

SSL/TLS information

Use modern security software and cipher suites.