Skip to main content

​
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: 
type AddressType = | "RESIDENTIAL1" //
Primary current address | "RESIDENTIAL2" // Previous address | "POSTAL" //
Mailing address
The legacy RESIDENTIAL type will be removed in the next major API version. Use RESIDENTIAL1 instead.

​
Address Structure Options

Using structured addresses provides better matching results and improved data quality.
FieldTypeDescription
unitNumberstringUnit/apartment/suite number
streetNumberstringStreet number (can be alphanumeric, e.g., “3A”)
streetNamestringName of the street
streetTypestringStreet type (e.g., Road, St, Ave)
townstringTown/city name
suburbstringSuburb (optional, use only if different from town)
statestringState abbreviation (e.g., VIC, TX)
regionstringCounty/province (optional)
postalCodestringPostal/ZIP code
countrystringISO-3166-alpha-3 country code
{
  "addresses": [{
    "addressType": "RESIDENTIAL1",
    "country": "AUS",
    "postalCode": "2000",
    "state": "NSW",
    "streetName": "Main",
    "streetNumber": "42",
    "streetType": "Street",
    "town": "Sydney",
    "unitNumber": "1"
  }]
}

​
Option 2: Long-Form Address

Use this format when structured address data isn’t available.
{
  "addresses": [
    {
      "addressType": "RESIDENTIAL1",
      "country": "AUS",
      "longForm": "LEVEL 8, 417 ST KILDA ROAD, MELBOURNE, VIC, 3004"
    }
  ]
}

​
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