Skip to content

Configure a Live Address Lookup on a Form

This article walks through how to set up a live address lookup on a ProcessFactorial Form. When a user types into an address field, search results appear as a dropdown list beneath the field. When they select an address, the form automatically populates the individual address components (street, city, postcode, etc.).

Before you begin: This feature requires two Integration Workflows to be set up in the Integrations section of the portal — one for searching addresses and one for retrieving the selected address details. If your integration workflows have not been configured yet, refer to the Create Address Lookup Integration article first.

How It Works

The address lookup uses two events on the form:

  1. OnKeyPressed — As the user types, the form calls the Search Integration Workflow, which returns a list of matching addresses. These are displayed as a dropdown beneath the field.
  2. OnUpdate — When the user selects an address from the list, the form calls the Save Integration Workflow, which returns the full address components. These are mapped to individual fields on the form.

Step 1: Create the Form Fields

Create the following fields on your form. The exact labels and field IDs can be anything you choose — the table below shows the suggested configuration.

Field Name Display Data Type Format Purpose
Country Lookup (or String) Type Ahead Filters address search results to a specific country. Must resolve to a Country Name, ISO2 code, or ISO3 code.
Address String Type Ahead The main search field. Users type here to search for addresses.
Line 1 String Standard First line of the selected address
Suburb / District String Standard Suburb or district of the selected address
City String Standard City of the selected address
Region String Standard Region / state of the selected address
Postcode String Standard Postcode / ZIP code of the selected address
Latitude Decimal Standard Latitude coordinate (populated automatically)
Longitude Decimal Standard Longitude coordinate (populated automatically)

Tip: You can map only the fields that are relevant to your use case. Not all address components need to be captured.

This event fires every time the user types a character in the Address field and presents matching addresses in a dropdown.

  1. Open the Address field for editing.
  2. Go to the Events tab.
  3. Select OnKeyPressed and click Add Action.
  4. Choose Integrate as the action type.
  5. Give the action a name (e.g., "Search for address") and description.
  6. Select the Search Integration Workflow (configured in the Integrations section).
  7. Map the integration workflow parameters to form fields:
    • Street Text → Map to the Address field's value (where the user is typing)
    • Country Text → Map to the Country field's value (or the ISO code if using a lookup)
  8. Under Use Integration Workflow to, select Show as Drop-Down Results.

Screenshot placeholder: OnKeyPressed event configuration

What this does: When the user types, the form sends the current search text and country to the Search Integration Workflow. The results are displayed as a clickable list beneath the Address field.

Step 3: Configure the OnUpdate Event (Populate Address Details)

This event fires when the user selects an address from the dropdown list, and fills in the individual address components.

  1. Still on the Address field's Events tab, select OnUpdate and click Add Action.
  2. Choose Integrate as the action type.
  3. Give the action a name (e.g., "Fetch address details") and description.
  4. Select the Save Integration Workflow (configured in the Integrations section).
  5. Map the Address Key parameter to the Address field's key property. This key is automatically set when the user selects an address from the search results.
  6. Under Use Integration Workflow to, select Populate Fields on Form.

  7. In the Sample Return Message box, paste a sample response that matches the structure your workflow returns. For example:

    {
  "line1": "123 Main Street",
  "city": "Wellington",
  "district": "Te Aro",
  "postcode": "6011",
  "region": "Wellington",
  "latitude": -41.2865,
  "longitude": 174.7756
}

  8. Below the sample, map each returned field to the corresponding form field:

    Return Property Map To
    line1 Line 1 field
    city City field
    district Suburb / District field
    postcode Postcode field
    region Region field
    latitude Latitude field
    longitude Longitude field

    Remember to click Save after each mapping.

Screenshot placeholder: OnUpdate event configuration

User Experience

When a user fills in the form:

  1. They start typing in the Address field.
  2. After a brief pause, a dropdown appears beneath the field showing matching addresses.
  3. They click on their address from the list.
  4. The form automatically fills in Line 1, City, Postcode, and any other mapped fields.
  5. The user can review and adjust the populated fields if needed.

Troubleshooting Tips

Symptom Likely Cause
No results appear when typing The Search Integration Workflow is not configured correctly, or the Country field is empty / invalid
Results appear but selecting one does nothing The OnUpdate event is missing, or the Address Key parameter is not mapped to the field's key property
Address fields are not populated The field mappings in the OnUpdate event are incomplete, or the field IDs in the Sample Return Message do not match
The dropdown flickers or closes immediately Check that the Address field is set to Type Ahead format