Working With Addresses

Key Requirements

Address ID Required for Updates

When updating an existing address, always include the addressId. You can retrieve it from the addresses array in the entity response.

Country Code Required

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

V2 Address Model: What’s Changed

The v2 address schema introduces two key structural changes from v1: 1. type + status replaces addressType In v1, address purpose and history were encoded in a single addressType field (e.g., RESIDENTIAL1, RESIDENTIAL2). In v2, these are separated:

type — what kind of address it is (e.g., RESIDENTIAL, POSTAL)
status — the temporal state of that address (CURRENT, PREVIOUS, FUTURE)

2. Field names align to global address standards

v1 Field	v2 Field	Notes
`addressType`	`type`	See `Address-TypeEnum` below
`town`	`locality`	Town, suburb, village, or city
`suburb`	`neighborhood`	Only needed when suburb differs from locality
`state`	`subdivision`	Use ISO 3166-2 sub-division code (e.g., `VIC`, `TX`)
`region`	`district`	District, county, province, or cantonment

Address Types

The type field accepts the following values:

Value	Description
`RESIDENTIAL`	Personal residential address
`POSTAL`	Individual mailing address
`BUSINESS`	Business address
`REGISTERED_OFFICE`	Registered office address
`PLACE_OF_BUSINESS`	Principal place of business
`OFFICIAL_CORRESPONDANCE`	Business postal/mailing address
`PLACE_OF_BIRTH`	Place of birth
`OFFICE_LOCALITY`	Office locality
`AUTHORITATIVE_RESIDENTIAL`	Authoritative residential address returned by a data source
`OTHER`	Any other address type

Use type in conjunction with status to express address history. For example, a current home address is type: RESIDENTIAL, status: CURRENT. A previous home address is type: RESIDENTIAL, status: PREVIOUS.

The v1 RESIDENTIAL1 / RESIDENTIAL2 pattern is not used in v2. Use RESIDENTIAL with status: CURRENT or PREVIOUS instead.

Address Status

The status field must be used alongside type to indicate the temporal state of the address.

Value	Description
`CURRENT`	The address is currently in use
`PREVIOUS`	The address was used in the past
`FUTURE`	The address is planned for future use

Address Structure Options

Option 1: Structured Address (Recommended)

Providing structured address components produces better matching results and improved data quality than long-form input.

Address Field Reference

Field	Type	Required	Description
`addressId`	string	For updates	Assigned when an address is added. Must be included when modifying an existing address.
`type`	string		Address type. See `Address-TypeEnum`.
`status`	string		Address status: `CURRENT`, `PREVIOUS`, or `FUTURE`. Use with `type`.
`unitNumber`	string		Unit, apartment, flat, or suite number
`buildingName`	string		Name of the building, apartment block, or condominium
`streetNumber`	string		Property number on the street. Can be alphanumeric (e.g., `3A`)
`streetName`	string		Name of the street. See note below on `addressLine1` input.
`streetType`	string		Street type (e.g., `Road`, `Street`, `Ave`, `Circuit`)
`locality`	string		Town, village, suburb, or city
`neighborhood`	string		Suburb or neighborhood — only supply if you also need a separate `locality` value
`subdivision`	string		State or administrative sub-division. Use ISO 3166-2 code (e.g., `VIC`, `TX`)
`district`	string		District, county, province, or cantonment
`postalCode`	string		Postal or ZIP code
`country`	string	Required	ISO 3166-1 alpha-3 country code (e.g., `AUS`, `USA`, `GBR`)
`careOf`	string		Individual or business at this address, if different from the entity name
`validFrom`	Date		Date this address first became active. Used primarily with business addresses.
`validTo`	Date		Date this address was no longer in use. Used primarily with business addresses.

Structured Address Example (AUS)

    {
      "addresses": [
        {
          "type": "RESIDENTIAL",
          "status": "CURRENT",
          "unitNumber": "1",
          "streetNumber": "100",
          "streetName": "South",
          "streetType": "ST",
          "locality": "Sydney",
          "subdivision": "NSW",
          "postalCode": "2000",
          "country": "AUS"
        }
      ]
    }

Update Address Example (AUS)

When updating an existing address, include addressId to target the correct record.

    {
      "addresses": [
        {
          "addressId": "<existing-address-id>",
          "type": "RESIDENTIAL",
          "status": "CURRENT",
          "streetNumber": "123",
          "streetName": "King",
          "streetType": "Street",
          "locality": "Melbourne",
          "subdivision": "VIC",
          "postalCode": "3000",
          "country": "AUS"
        }
      ]
    }

Option 2: Long-Form Address

Use this format only when structured address components are not available. The API will attempt to parse longForm into its constituent fields. Results are not guaranteed — ambiguous or unparsable addresses will return an error.

{
  "addresses": [
    {
      "type": "RESIDENTIAL",
      "status": "CURRENT",
      "country": "AUS",
      "longForm": "LEVEL 8, 417 ST KILDA ROAD, MELBOURNE, VIC, 3004"
    }
  ]
}

Using `streetName` for Combined Address Input

If your system stores street details in a single field (commonly called addressLine1, e.g., "42 Main Street"), place the full value in streetName. The streetName field can accommodate combined address elements when discrete fields are unavailable.

For best matching results, provide streetNumber, streetName, and streetType as separate fields wherever possible.

✅ Preferred: streetNumber: "42", streetName: "Main", streetType: "Street"
⚠️ Acceptable fallback: streetName: "42 Main Street" (combined addressLine1 value)

Read-Only Response Fields

The following address fields are returned in API responses but cannot be set in request payloads:

Field	Description
`addressId`	Assigned by FrankieOne when an address is first created
`sourceId`	Links to the `informationSources` map — indicates which data source populated this address
`unstructuredLongForm`	Raw, unformatted address as received from the source. Not normalised or standardised.

Additional Resources

ISO Country Codes Reference

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

​Key Requirements

Address ID Required for Updates

Country Code Required

​V2 Address Model: What’s Changed

​Address Types

​Address Status

​Address Structure Options

​Option 1: Structured Address (Recommended)

​Option 2: Long-Form Address

​Using streetName for Combined Address Input

​Read-Only Response Fields

​Additional Resources

ISO Country Codes Reference

Key Requirements

V2 Address Model: What’s Changed

Address Types

Address Status

Address Structure Options

Option 1: Structured Address (Recommended)

Option 2: Long-Form Address

Using `streetName` for Combined Address Input

Read-Only Response Fields

Additional Resources