Working with Addresses | FrankieOne

Overview of Addresses

Addresses are a key part of the KYC process, used to verify the identity of an entity and ensure authenticity. This guide provides an overview of how to create and manage addresses using the FrankieOne KYC v2 API.

Don't forget the Address ID

When updating an address, include the addressId field. This is provided in the response message when you first add the address. You can retrieve the addressId (and other IDs) by calling the GET /v2/{entityType}/{entityId} API.

Country is Mandatory

The country field is required and must be one of the ISO-3166-alpha-3 codes.

See here: List of ISO 3166 country codes

Address Types

Addresses can have various types. While optional, specifying the type is recommended for better processing and validation. The following types are commonly used:

RESIDENTIAL: The primary address used to determine the country of residence and current address.
Note: The use of RESIDENTIAL for this purpose will be deprecated in the next major API version.
POSTAL: A mailing address, also used as the current residential address if no RESIDENTIAL type is provided.

Street Address and the `streetName` Field

Breaking down an address into its constituent parts is ideal, but the streetName field is flexible. You can combine streetNumber, streetName, and streetType into the streetName field if necessary.

Break Down Address Fields

While combining fields is supported, breaking the address into individual fields yields the best matching results.

Structured Addresses

Using structured addresses is recommended for accuracy. Map the following fields 1-to-1:

Field Name	Description	Type
`type`	The type of address, e.g., `RESIDENTIAL`, `POSTAL`.	String (enum)
`typeDescription`	A description of the address for reference.	String
`unitNumber`	Unit/Apartment/Flat/Suite number.	String
`streetNumber`	The number on the street (can be alphanumeric, e.g., 3A).	String
`streetName`	The name of the street.	String
`streetType`	The street type, e.g., Road, St, Ave, Circuit.	String
`buildingName`	The name of the building, apartment block, or condo.	String
`locality`	The locality, town, village, suburb, or city.	String
`district`	The district, region, county, or province.	String
`neighborhood`	The neighborhood or suburb. Use only if `locality` is already captured and additional detail is needed.	String
`subdivision`	The administrative area, state, or subdivision. Abbreviations (e.g., “VIC”) and full names (e.g., “Victoria”) are acceptable.	String
`country`	The ISO-3166-1 alpha-3 country code.	String
`postalCode`	The postal or zip code.	String
`careOf`	Name of the individual or business at this address, if different from the entity’s name.	String
`longForm`	The full address as a single string. Use only if breaking down the address is not possible.	String
`status`	The status of the address (e.g., `CURRENT`, `FUTURE`).	String (enum)
`validTo`	The date when the entity will stop using this address.	Date
`validFrom`	The date when the entity started using this address.	Date