What are freeform and structured addresses in the API?

Addresses on profiles have two types:

STRUCTURED (recommended): This address is structured into its individual components, for example, postal code, locality, and street number. Data providers use this type.
FREEFORM (not recommended): This address is made up of a country, provided as an ISO3 country code, and a free text field that contains the rest of the address. Data providers cannot use this type.

If you send Passfort a FREEFORM address, we'll convert it to a STRUCTURED address automatically so we can send it to the data provider to run the check. However, this conversion process can result in incorrect addresses.

For this reason, we always recommend you send us STRUCTURED addresses in your live environment.

To learn about the tools you can use to allow your customers to enter addresses in an unstructured way, see Capturing unstructured addresses.

A profile's address is stored in its COLLECTED_DATA, collected_data.address_history.address for individual profiles, and collected_data.metadata.addresses for company profiles. To learn more, see Get collected data in the developer resources.

Structured address fields

Parameters

The following parameters are used in STRUCTURED addresses.

Key	Value	Description	Passfort portal name
`type` Required String	`STRUCTURED`	The address type.	-
`country` Required String	Sample value: `GBR` The country must be provided as an ISO3 code.	The country of the address.	Country
`county` Optional String	Sample value: `Middlesex`	The county of the address. Note that a US state or a Canadian province or territory should not go here.	County
`locality` Optional String	Sample value: `London`	The city or town of the address.	City
`original_freeform_address` Optional String	Sample value: `, , 38, Crown Street, London, , Middlesex, , W1 2ZT`	The freeform address, prior to structuring attempts.	-
`original_structured_address` Optional Object	For a sample value, see the following Example.	This field is deprecated and is not used. It contains the same data as the rest of the structured address.	-
`postal_code` Optional String	Sample value: `W1 2ZT`	The postal code or zip code of the address.	Postal code
`postal_town` Optional String	Sample value: `London`	The postal town or district of the address. For smaller localities, mail may be posted to a different town, if that's where the nearest post office is located. Get a list of postal towns within the UK.	Town
`premise` Optional String	Sample value: `Princelet House`	The name of the building.	Building name
`route` Optional String	Sample value: `Crown Street`	The name of the route or street.	Street
`state_province` Required for US, Canada, Australia Optional for all other countries String	Sample value: `ON`	The state, province, or territory of the address. The format follows the state code of the ISO-3166-2 standard. Note that a UK county should not go here.	State
`street_number` Optional String	Sample value: `38`	The street number of the address.	Building number
`subpremise` Optional String	Sample value: `Flat C`	The subaddress within the building. Typically this is a flat number.	Flat number

Example

This is an example of a STRUCTURED address.

{
    "type": "STRUCTURED",
    "country": "GBR",
    "county": "Middlesex", 
    "locality": "London",
    "original_freeform_address": ", , 38, Crown Street, London, , Middlesex, , W1 2ZT",
    "original_structured_address": {
        "country": "GBR",
        "county": "Middlesex",
        "locality": "London",
        "postal_code": "W1 2ZT",
        "postal_town": "",
        "premise": "",
        "route": "Crown Street",
        "state_province": "",
        "street_number": "38",
        "subpremise": ""
    }
    "postal_code": "W1 2ZT",
    "postal_town": "",
    "premise": "",
    "route": "Crown Street",
    "state_province": "",
    "street_number": "38",
    "subpremise": ""
}

Freeform addresses fields

Passfort strongly recommends using the tools in Capturing unstructured addresses rather than sending FREEFORM addresses.

Parameters

The following parameters are used in FREEFORM addresses.

Key	Value	Description
`type` Required String	`FREEFORM`	The address type.
`country` Required String	Sample value: `GBR` The country must be provided as an ISO3 code.	The country of the address.
`text` Required String	Sample value: `, , 38, Crown Street, London, , Middlesex, , W1 2ZT`	A free text description of the address.

Example

This is an example of the STRUCTURED address example written as a FREEFORM address.

{
    "type": "FREEFORM",
    "country": "GBR",
    "text": ", , 38, Crown Street, London, , Middlesex, , W1 2ZT"
}

Capturing unstructured addresses

If you're enabling your customers to enter addresses in an unstructured way, there are several tools you can use to convert them to STRUCTURED addresses.

We've given a few examples of tools for this conversion, but you can use any option that suits you.

Experian Data Quality

When you use Experian Data Quality, the fields will be mapped as follows.

Experian Data Quality field	Passfort profile address field
`countryISO1`	`country`
`locality1`	`locality`
`postalCode1`	`postal_code`
`locality2`	`postal_town`
`building1 or organisation1`	`premise`
`street1`	`route`
`provinceCode1`	`state_province`
`county1`	`county`
`streetNumber1`	`street_number`
`subBuilding1`	`subpremise`

GBG Loqate

If GBG Loqate is the right option for you, you can use Passfort as a reseller.

When you use GBG Loqate, the fields will be mapped for you as follows.

GBG Loqate field	Passfort profile address field
`CountryIso3`	`country`
`City`	`locality`
`PostalCode`	`postal_code`
`District`	`postal_town`
`BuildingName`	`premise`
`Street`	`route`
`ProvinceCode`	`state_province`
`BuildingNumber`	`street_number`
`SubBuilding`	`subpremise`

To learn more about how it works, see Address Search in the developer resources.

To add this configuration to your account, contact us.

When you use Passfort as a reseller, you can use Passfort credit to pay for address formatting.

Google Maps

You can use the Google Maps Autocomplete for Addresses and Search Terms API to capture STRUCTURED addresses.

The API offers javascript widgets that you may find easier to implement.

Map the fields from Google Map's address_components array as follows.

Google Maps `address_components` field	Passfort profile address field
`country` Note that you'll need to convert this field from an Alpha-2 code to an Alpha-3 (ISO3) code.	`country`
`locality`	`locality`
`postal_code`	`postal_code`
`postal_town`	`postal_town`
`premise`	`premise`
`route`	`route`
`administrative_area_level_1`	`state_province`
`street_number`	`street_number`
`subpremise`	`subpremise`

In this section:

Using Passfort