Freeform and structured address fields in the API

Addresses on profiles have two types:

STRUCTURED: This address is structured into its individual components, for example, postal code, locality, and street number, and is the preferred format utilized by data providers.
FREEFORM: 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 and is therefore not recommended.

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.

Note

When you submit an address for a profile, the country must be provided as an ISO3 code.

Some data providers may not support disputed countries. Check with your data provider to confirm which countries they support.

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.

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"
}

Tools to convert 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, Passfort recommends the following mapping.

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

When you use GBG Loqate, Passfort recommends the following mapping.

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.

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.

Passfort recommends mapping 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`

Additional information

In this section:

Freeform and structured address fields in the API

Structured address fields

Parameters

Example

Freeform addresses fields

Parameters

Example

Tools to convert unstructured addresses

Experian Data Quality

GBG Loqate

Google Maps

Additional information

Search results