Working With Addresses

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 Field

Type

Comment

unitNumber

string

Unit/Apartment/Flat/Suite/etc number

streetNumber

string

The number on the street. Generally a number, but can also be alphanumeric (e.g. 3A)

streetName

string

The 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
then the bulk of the address will be in this field.

If you can avoid it though, please try and keep things separate.

streetType

string

The street "type" - e.g. Road, St, Ave, Circuit, etc

town

string

The town/village/suburb/city

suburb

string

The suburb in the town/city. Only use this if you require a suburb AND a town/city, otherwise, just use the "town" parameter.

state

string

The state. Use local abbreviations, such as VIC(toria) or TX (Texas)

region

string

The county, province, cantonment (not always needed)

postalCode

string

The post code of the address.

country

string

Mandatory 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": "RESIDENTIAL",
                    "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"
    }
]

Did this page help you?