Skip to main content

​
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 Fieldv2 FieldNotes
addressTypetypeSee Address-TypeEnum below
townlocalityTown, suburb, village, or city
suburbneighborhoodOnly needed when suburb differs from locality
statesubdivisionUse ISO 3166-2 sub-division code (e.g., VIC, TX)
regiondistrictDistrict, county, province, or cantonment

​
Address Types

The type field accepts the following values:
ValueDescription
RESIDENTIALPersonal residential address
POSTALIndividual mailing address
BUSINESSBusiness address
REGISTERED_OFFICERegistered office address
PLACE_OF_BUSINESSPrincipal place of business
OFFICIAL_CORRESPONDANCEBusiness postal/mailing address
PLACE_OF_BIRTHPlace of birth
OFFICE_LOCALITYOffice locality
AUTHORITATIVE_RESIDENTIALAuthoritative residential address returned by a data source
OTHERAny 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.
ValueDescription
CURRENTThe address is currently in use
PREVIOUSThe address was used in the past
FUTUREThe address is planned for future use

​
Address Structure Options

Providing structured address components produces better matching results and improved data quality than long-form input.
FieldTypeRequiredDescription
addressIdstringFor updatesAssigned when an address is added. Must be included when modifying an existing address.
typestringAddress type. See Address-TypeEnum.
statusstringAddress status: CURRENT, PREVIOUS, or FUTURE. Use with type.
unitNumberstringUnit, apartment, flat, or suite number
buildingNamestringName of the building, apartment block, or condominium
streetNumberstringProperty number on the street. Can be alphanumeric (e.g., 3A)
streetNamestringName of the street. See note below on addressLine1 input.
streetTypestringStreet type (e.g., Road, Street, Ave, Circuit)
localitystringTown, village, suburb, or city
neighborhoodstringSuburb or neighborhood — only supply if you also need a separate locality value
subdivisionstringState or administrative sub-division. Use ISO 3166-2 code (e.g., VIC, TX)
districtstringDistrict, county, province, or cantonment
postalCodestringPostal or ZIP code
countrystringRequiredISO 3166-1 alpha-3 country code (e.g., AUS, USA, GBR)
careOfstringIndividual or business at this address, if different from the entity name
validFromDateDate this address first became active. Used primarily with business addresses.
validToDateDate this address was no longer in use. Used primarily with business addresses.
    {
      "addresses": [
        {
          "type": "RESIDENTIAL",
          "status": "CURRENT",
          "unitNumber": "1",
          "streetNumber": "100",
          "streetName": "South",
          "streetType": "ST",
          "locality": "Sydney",
          "subdivision": "NSW",
          "postalCode": "2000",
          "country": "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:
FieldDescription
addressIdAssigned by FrankieOne when an address is first created
sourceIdLinks to the informationSources map — indicates which data source populated this address
unstructuredLongFormRaw, 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