Working With Addresses

Suggest Edits

Common "Gotchas"

📘

Don't forget the Address ID

When updating an address, don’t forget to include the addressId field. This would have been in the response message when you first added the address.

You can always get the addressId (and all other IDs) if you call the GET /entity API call.


📘

Don't forget the Country

Don’t forget to include the country. This field is mandatory and must be one of the ISO-3166-alpha-3 codes.

See here: List of ISO 3166 country codes

Address Types

Addresses have a number of available addressType options. Whilst this is an optional field, it is good practice to include the type to assist with processing and checking. It is recommended that these following types be used:

RESIDENTIAL1 - This will be the primary address used when trying to determine the country of residence and primary current address. If RESIDENTIAL has been used for this, note that this will be deprecated and removed in the next major version of the API.

RESIDENTIAL2 - This is used as the previous address when checking against services that support this as an option

POSTAL - This is a mailing address. It is also used as the current residential address if no RESIDENTIAL1 or RESIDENTIAL type is found.

Street Address and the use of the streetName field

It can be hard to break down an address and so we’ve made the streetName field quite flexible.

Whilst it is best to break the address into it’s constituent parts, you can combine streetNumber, streetName and streetType into the streetName field if required.

🚧

It's better to break down the address fields

Whilst combining the fields is readily supported, best matching results are found when you break the address down into as many fields as you can

Structured Address

It is always best to use the structured address and map in 1-1 the following fields

API FieldTypeComment
unitNumberstringUnit/Apartment/Flat/Suite/etc number
streetNumberstringThe number on the street. Generally a number, but can also be alphanumeric (e.g. 3A)
streetNamestringThe name of the street

This field can in fact be a bit flexible, potentially containing the streetNumber and streetType as well. Most services in use can work it out.

If this field has been auto-populated by Google (see writeup here:

https://apidocs.frankiefinancial.com/docs/working-with-addresses#street-address-and-the-use-of-the-streetname-field
then the bulk of the address will be in this field.

If you can avoid it though, please try and keep things separate.
streetTypestringThe street "type" - e.g. Road, St, Ave, Circuit, etc
townstringThe town/village/suburb/city
suburbstringThe suburb in the town/city. Only use this if you require a suburb AND a town/city, otherwise, just use the "town" parameter.
statestringThe state. Use local abbreviations, such as VIC(toria) or TX (Texas)
regionstringThe county, province, cantonment (not always needed)
postalCodestringThe post code of the address.
countrystringMandatory field. The ISO-3166-1 country. You must use the alpha3 country code (e.g. AUS, USA, IDR, KOR, etc) We'll convert as needed.

Note the residential country is a KEY field for how we do our checks.

Example

"addresses": [
               {
                    "addressType": "RESIDENTIAL1",
                    "country": "AUS",
                    "postalCode": "2000",
                    "state": "NSW",
                    "streetName": "Main",
                    "streetNumber": "42",
                    "streetType": "Street",
                    "town": "Sydney",
                    "unitNumber": "1"
               }

If you do not have a structured address then yes use the long-form address:

"addresses": [
    {
        "addressType": "RESIDENTIAL1",
        "country": "AUS",
        "longForm": "LEVEL 8, 417 ST KILDA ROAD, MELBOURNE, VIC, 3004"
    }
]

Updated 5 months ago