Working With Addresses | FrankieOne

Key Requirements

Address ID Required

Always include the addressId when updating addresses. You can retrieve it using the GET /entity endpoint.

Country Code Required

The country field is mandatory and must use ISO-3166-alpha-3 codes (e.g., USA, AUS, GBR).

Available Address Types

We support several address types to help with processing and validation:

Address Types

1 type AddressType = | "RESIDENTIAL1" //
2 Primary current address | "RESIDENTIAL2" // Previous address | "POSTAL" //
3 Mailing address

The legacy RESIDENTIAL type will be removed in the next major API version. Use RESIDENTIAL1 instead.

Address Structure Options

Option 1: Structured Address (Recommended)

Using structured addresses provides better matching results and improved data quality.

Address Field Reference

Field	Type	Description
`unitNumber`	string	Unit/apartment/suite number
`streetNumber`	string	Street number (can be alphanumeric, e.g., “3A”)
`streetName`	string	Name of the street
`streetType`	string	Street type (e.g., Road, St, Ave)
`town`	string	Town/city name
`suburb`	string	Suburb (optional, use only if different from town)
`state`	string	State abbreviation (e.g., VIC, TX)
`region`	string	County/province (optional)
`postalCode`	string	Postal/ZIP code
`country`	string	ISO-3166-alpha-3 country code

Structured Address Example

1 {
2   "addresses": [{
3     "addressType": "RESIDENTIAL1",
4     "country": "AUS",
5     "postalCode": "2000",
6     "state": "NSW",
7     "streetName": "Main",
8     "streetNumber": "42",
9     "streetType": "Street",
10     "town": "Sydney",
11     "unitNumber": "1"
12   }]
13 }

Option 2: Long-Form Address

Use this format when structured address data isn’t available.

1 {
2   "addresses": [
3     {
4       "addressType": "RESIDENTIAL1",
5       "country": "AUS",
6       "longForm": "LEVEL 8, 417 ST KILDA ROAD, MELBOURNE, VIC, 3004"
7     }
8   ]
9 }

Street Address Flexibility

While the streetName field is flexible and can contain combined address elements, we recommend separating address components when possible:

✅ Preferred: Separate streetNumber, streetName, and streetType
⚠️ Acceptable: Combined in streetName

Additional Resources

ISO Country Codes Reference

View the complete list of ISO 3166-1 alpha-3 country codes