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 |
Required String |
| The address type. | - |
Required String | Sample value: The country must be provided as an ISO3 code. | The country of the address. | Country |
Optional String | Sample value: | The county of the address. Note that a US state or a Canadian province or territory should not go here. | County |
Optional String | Sample value: | The city or town of the address. | City |
Optional String | Sample value: | The freeform address, prior to structuring attempts. | - |
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. | - |
Optional String | Sample value: | The postal code or zip code of the address. | Postal code |
Optional String | Sample value: | 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 |
Optional String | Sample value: | The name of the building. | Building name |
Optional String | Sample value: | The name of the route or street. | Street |
Required for US, Canada, Australia Optional for all other countries String | Sample value: | 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 |
Optional String | Sample value: | The street number of the address. | Building number |
Optional String | Sample value: | 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 |
Required String |
| The address type. |
Required String | Sample value: The country must be provided as an ISO3 code | The country of the address. |
Required String | Sample value: | 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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GBG Loqate
When you use GBG Loqate, Passfort recommends the following mapping.
GBG Loqate field | Passfort profile address field |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 | Passfort profile address field |
Note that you'll need to convert this field from an Alpha-2 code to an Alpha-3 (ISO3) code. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|