US Address Enrichment API

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

HTTP Request
HTTP Response
1. Results
Supplementary Materials
1. SSL/TLS Information
2. Try the Address Enrichment API Demo

HTTP Request: URL Composition

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

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

Here is a more granular examination of the example above:

URL Components	Values	Notes
Scheme	`https`	NOTE: Non-secure `http` requests are not supported
Hostname	`us-enrichment.api.smarty.com`
Path	`/lookup`
Smarty Key	`/1000000`	The unique id associated with the address you are looking for
Dataset	`/property`	The specific type of data you need
Data-Subset	`/principal` `/financial`	The specific subset of the dataset you need
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

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

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`

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
`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.
`400`	Bad Request (Malformed Payload): The request body was blank or otherwise malformed.
`429`	Too Many Requests: We restrict the number of requests coming from a given source over too short of a time.
`413`	Request Entity Too Large: The request body was larger than 64 Kilobytes.
`200`	OK (success!): The response body is a JSON object containing metadata about the results and zero or more extracted addresses from the input provided with the request. See the annotated example below for details.

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",
					...
				}
			],
			...
		},
	}

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 smarty-key returned.

HTTP GET - SmartyKey Not Valid

Precondition	SmartyKey does not exist.
Action	`https://us-enrichment.api.smarty.com/lookup/111111/property/principal`
Result	Empty results returned.

HTTP GET - SmartKey Valid. Data doesn't exist.

Precondition	SmartyKey does exist. No data associated with SmartyKey.
Action	`https://us-enrichment.api.smarty.com/lookup/111111/property/principal/`
Result	Empty results returned.

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 smarty-key returned.

Data Sets

US Property 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
Financial Data (property/financial)
- Dataset that contains historical financial data attributes pertaining to the property and property owner.

SSL/TLS Information

Use modern security software and cipher suites.