# Smarty

> Validate and verify US addresses using the Smarty US Street Address API. Get delivery point validation, residential/commercial classification, and standardized address components.

Source: https://cotera.co/docs/reference/tools/individual-tools/smarty

---

**Authentication Type:** Password
**Description:** Validate and verify US addresses using the Smarty US Street Address API. Get delivery point validation, residential/commercial classification, and standardized address components.

***

## Authentication

To authenticate, you'll need Smarty API credentials. Learn how to create them in the [Smarty documentation](https://www.smarty.com/docs/cloud/authentication).

You will need:

* **Auth ID** - Use as the username
* **Auth Token** - Use as the password

***

## Address Validation

Validate and verify US street addresses with comprehensive delivery information.

### Validate Address

Validates a US address and returns detailed information including delivery point validation, address components, metadata (county, carrier route, coordinates), and analysis results.

**Operation Type:** Query (Read)

**Parameters:**

* **street** `string` (required): The street line of the address, or the entire address for freeform input (max 100 chars)
* **street2** `string` (nullable): Any extra address information
* **secondary** `string` (nullable): Apartment, suite, or office number (e.g., "Apt 52")
* **city** `string` (nullable): The city name
* **state** `string` (nullable): The state name or abbreviation
* **zipcode** `string` (nullable): The ZIP Code
* **candidates** `number` (nullable): Maximum number of address candidates to return (1-10, default 1)
* **match** `string` (nullable): Match output strategy: strict (default), invalid (includes invalid addresses), or enhanced (more aggressive matching)

**Returns:**

* **addresses** `array of objects`: Array of validated address candidates
  * **inputIndex** `number`: Order in which address was submitted
  * **candidateIndex** `number`: Index of this candidate for the input
  * **addressee** `string` (nullable): Name of person or company
  * **deliveryLine1** `string` (nullable): First delivery line (street address)
  * **deliveryLine2** `string` (nullable): Second delivery line if needed
  * **lastLine** `string` (nullable): City, state, and ZIP combined
  * **deliveryPointBarcode** `string` (nullable): 12-digit POSTNET barcode
  * **smartyKey** `string` (nullable): Smarty's unique identifier for the address
  * **components** `object` (nullable): Standardized address components
    * **urbanization** `string` (nullable): The neighborhood (Puerto Rico only)
    * **primaryNumber** `string` (nullable): The house, PO Box, or building number
    * **streetName** `string` (nullable): The name of the street
    * **streetPredirection** `string` (nullable): Directional info before street name (N, SW, etc.)
    * **streetPostdirection** `string` (nullable): Directional info after street name (N, SW, etc.)
    * **streetSuffix** `string` (nullable): Abbreviated street type (St, Ave, Blvd, etc.)
    * **secondaryNumber** `string` (nullable): Apartment or suite number
    * **secondaryDesignator** `string` (nullable): Describes location within building (Ste, Apt, etc.)
    * **cityName** `string` (nullable): The USPS-preferred city name
    * **stateAbbreviation** `string` (nullable): Two-letter state abbreviation
    * **zipcode** `string` (nullable): 5-digit ZIP Code
    * **plus4Code** `string` (nullable): 4-digit add-on code
    * **deliveryPoint** `string` (nullable): Last two digits of house/box number
    * **deliveryPointCheckDigit** `string` (nullable): Check digit for 11-digit barcode
  * **metadata** `object` (nullable): Address metadata and geographic information
    * **recordType** `string` (nullable): Type of record matched (F=Firm, G=General Delivery, H=High-rise, P=PO Box, R=Rural Route, S=Street)
    * **zipType** `string` (nullable): Type of ZIP Code (Unique, Military, POBox, Standard)
    * **countyFips** `string` (nullable): 5-digit county FIPS code
    * **countyName** `string` (nullable): Name of the county
    * **carrierRoute** `string` (nullable): Postal carrier route (e.g., C007, R123)
    * **congressionalDistrict** `string` (nullable): Congressional district (01-53 or AL)
    * **rdi** `string` (nullable): Residential Delivery Indicator (Residential, Commercial, or blank)
    * **latitude** `number` (nullable): Geographic latitude
    * **longitude** `number` (nullable): Geographic longitude
    * **precision** `string` (nullable): Coordinate precision level
    * **timeZone** `string` (nullable): Time zone name
    * **utcOffset** `number` (nullable): UTC offset in hours
    * **dst** `boolean` (nullable): Whether time zone observes daylight saving time
  * **analysis** `object` (nullable): Address validation analysis results
    * **dpvMatchCode** `string` (nullable): Delivery Point Validation status (Y=Confirmed, N=Not confirmed, S=Confirmed ignoring secondary, D=Missing secondary)
    * **dpvFootnotes** `string` (nullable): DPV footnotes providing additional validation info
    * **dpvCmra** `string` (nullable): Whether address is a Commercial Mail Receiving Agency (Y/N)
    * **dpvVacant** `string` (nullable): Whether delivery point is vacant (Y/N)
    * **dpvNoStat** `string` (nullable): Whether address is listed as no-stat by USPS (Y/N)
    * **active** `string` (nullable): Whether address is active (Y)
    * **footnotes** `string` (nullable): Footnotes indicating changes made to input

**Example Usage:**

```json
{
  "street": "1600 Amphitheatre Parkway",
  "city": "Mountain View",
  "state": "CA",
  "zipcode": "94043",
  "candidates": 3,
  "match": "strict"
}
```

### Get RDI

Gets the Residential Delivery Indicator (RDI) for a US address. Returns whether the address is Residential or Commercial.

**Operation Type:** Query (Read)

**Parameters:**

* **street** `string` (required): The street line of the address, or the entire address for freeform input
* **city** `string` (nullable): The city name
* **state** `string` (nullable): The state name or abbreviation
* **zipcode** `string` (nullable): The ZIP Code

**Returns:**

* **rdi** `string` (nullable): Residential Delivery Indicator: "Residential", "Commercial", or null if not available
* **deliveryLine1** `string` (nullable): The validated street address
* **lastLine** `string` (nullable): City, state, and ZIP combined
* **isValid** `boolean`: Whether the address was found and validated

**Example Usage:**

```json
{
  "street": "1 Apple Park Way",
  "city": "Cupertino",
  "state": "CA",
  "zipcode": "95014"
}
```

***

## Common Use Cases

**Address Standardization:**

* Standardize addresses before storing in your database
* Convert freeform address input into structured components
* Ensure consistent address formatting across your application

**Delivery Validation:**

* Verify that addresses are deliverable before shipping
* Check for vacant or inactive delivery points
* Identify Commercial Mail Receiving Agencies (CMRAs)

**Business Classification:**

* Determine if an address is residential or commercial for shipping rates
* Apply different business rules based on address type
* Identify business locations vs home addresses

**Geographic Enrichment:**

* Get latitude/longitude coordinates for mapping
* Retrieve county, time zone, and congressional district information
* Enrich customer records with geographic metadata