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

Structured Address Example

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

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

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