Skip to main content

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.

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