Salesforce CRM Integration Guide

Download the Loqate app from the Salesforce AppExchange

The Loqate app, available from the Salesforce AppExchange, allows you to quickly and easily add Loqate address verification services to your instance of Salesforce CRM, providing type-ahead lookup functionality for address fields, and validation for both email addresses and phone numbers. With some or all of these services enabled, you can reduce the amount of time spent inputting customer details, and improve the accuracy of your database.

Setup Video

Available services

The Loqate app gives you access to these Loqate services in your Salesforce CRM instance:

Address Capture, which provides a type-ahead solution for address input - referred to in Salesforce as Address finder
Email Validation, which ensures the accuracy of customer email addresses - referred to in Salesforce as Email validator
Phone Validation, which ensures the accuracy of customer phone numbers - referred to in Salesforce as Phone number validator

Use cases

There are two ways of using Loqate services in your Salesforce instance:

On record pages, using Lightning components - all Loqate services
During actions, using Flows (recommended) or Visualforce components (legacy, and not recommended) - Address Capture only

The Process section below will take you through how to set up both methods, beginning with overall installation before moving onto setting up mappings for use on record pages, then setting up Flows. For details of Visualforce setup, see the separate Legacy Visualforce elements section at the end of this article.

Prerequisites

Before installing the Loqate app you will need:

A live Salesforce CRM account
A live Loqate account
A Loqate API key*

*Note that your API key is designed to be an open access key to your account - there are security controls within your Loqate account to ensure this is not abused. The key used in the app will be your primary mechanism of reporting for usage, so we recommend create a new key rather than reusing one you may already have on a website or other application.

Process

There are a few quick steps to get the Loqate app up and running:

Install the app
Assign permissions
Add your Loqate API key
Set up address mappings
Add Loqate widgets to your object pages
Optional: Address finder settings
Add address Capture to Flows

If you only want to use the Email validator and Phone validator controls, you can skip the address mapping step. If you want to also use the Address finder control though, please follow all of the steps below.

Installing the Loqate app

We recommend installing the Loqate app directly from the Salesforce AppExchange - adding the app from here will ensure you’re always installing the latest version.

Setting permissions

The Loqate app ships with one administrator permission set and three end-user permission sets. Assign Loqate Administrator to whoever configures the package, and one of the Loqate User sets to anyone who needs to capture addresses on a page, form, or flow. See Permission Sets for a full description of each set and guidance on which end-user set to pick for your org. Set the permissions as required for each of your users under Setup → Permission Sets, then move on to the next step.

App setup

With the app installed and permission sets assigned, the next step is to add your Loqate API key to the app, which you can do in the API Settings section of the Loqate Settings page.

Note: accessing the Settings page requires the Loqate Administrator permission set. Select the Loqate app from the App Launcher, then copy and paste your API key into the API Settings section and click Save. With that done, the Email validator and Phone validator controls are both enabled and can be added to pages - if you only want to use those two controls, you can skip ahead to the Loqate widgets section. To add the Address finder control as well, follow the steps below for creating address mappings.

Address mappings

For each address type that you want to populate using the Address finder control, you need to create an address mapping. This may involve creating multiple mappings for a single object - for example, for the Contact object you might create one mapping for the ‘Mailing’ address and another for the ‘Other’ address. You can create address mappings in the Settings page of the Loqate app.

In the Mappings section, click New Mapping
Name your mapping (we recommend using a distinct and memorable name, to distinguish it from other address types - for example, “Contact Mailing”)
From the ‘Select an object’ drop-down, choose the object that you want to create a mapping for

Click the + Add Field button, then from the ‘Select a field’ drop-down choose a field that you want to populate with address data
From the ‘Select a element’ drop-down, choose a Loqate element to map to your chosen field

Click the Add Field Mapping button to save and add your new mapping to the list

You can create as many mappings as you need by just repeating these steps.

Custom mappings

If required, you can also use custom address mappings.

When selecting an element to map to a field, choose the custom format option option from the drop-down list
In the ‘Custom pattern’ field that appears, enter your custom field mapping
For example, entering ”, will concatenate line1 and line2, separated by a comma and a space (assuming line2 is available - if not, only line1 will be included)

See the Formatting section of our Advanced Setup Guide for more information about custom field values

Loqate widgets

In order to start using Loqate functionality, you need to add each control (i.e. Address finder, Email validator and Phone validator, where appropriate) to your object pages.

From the Details tab on the Contacts page, select Settings and then Edit Page

In the Lightning App Builder, look for the Loqate controls in the Custom section of the Components menu. You should see loqateAddressCapture, loqateEmailVerification and loqatePhoneVerification:

You can drag each of these onto your page, placing them where you want them. Here’s an example showing all three components added to the right-hand side of the page:

Once you’ve placed all of the components, Save and Activate the page to be able to start using them
Repeat this process for all pages that you want to add the Loqate features to

Optional: Address finder settings

The Address finder control includes some additional settings which you can amend if required. To see these settings, select an Address finder control where it’s been added to one of your pages.

You’ll need to amend the settings for each instance of the control.

Field mappings

By default, the Address finder control will display a select box listing all of the mappings you’ve created for the object on which the control has been placed. You can then select the relevant mapping you want to use. Optionally though, you can lock the Address finder control to a particular mapping by entering a specific mapping name in the Field Mappings box. The control will no longer display the ‘Select a mapping’ box, and will instead always use the mapping you’ve chosen.

Address title prefix

If you have multiple Address finder controls on a single page (for example if you’ve locked one or more of them to particular mappings), it’s useful to give each one a specific name to clearly differentiate them. You can use this setting to add additional text to the start of each control’s title. Whatever text you enter in the Address Title Prefix box will be added at the start of its title - so for example if you have both ‘mailing’ and ‘other’ address fields on a page, add “Mailing” into this box for one of the controls so that it will display as “Mailing Address finder”.

Add Address Capture to Flows

Follow these steps to add Address Capture to a Flow:

Open the Flow editor for the Flow you want to add Address Capture to. For this example we’ll use Create a case

From here, choose a screen to add the Loqate control to, and open the screen editor. In this example we’ll use the Confirm Customer Info screen

The Loqate Address Capture component will be listed under Custom, so scroll down to that and drag the component onto your view

Make sure you add a name into the API Name field
You shouldn’t need to fill in any of the other fields, as they’re in place to allow for the Flows data model
Click Done, then run or debug the Flow to view the control and output

From here you can see that the Search for an address field is present
Having searched for and found an address, click Next to move to the next screen - in this case the Confirm Customer Details screen

Here you can see the returned address data, which you can then use in the rest of the Flow

Handling Custom Field Types in Flows

When using the Loqate Flow action to return custom fields, the output values are returned as Text. This is fine for most scenarios, but can cause issues when mapping onto Salesforce standard fields that expect other data types (for example, MailingLatitude and MailingLongitude, which are Number fields). If you attempt to map a Text resource directly to a Number field in a Create or Update Records element, Flow will block the mapping. Solution: Use a Number Formula Resource You can convert the returned Text into a Number inside your Flow before mapping. Steps:

In Flow Builder, open the Manager panel and click New Resource.
Select Resource Type: Formula.
Give it an API Name (e.g. latNumber).
Set Data Type: Number.
Set Decimal Places: 6 (or another precision suitable for coordinates).
Enter the following formula, referencing the Text output from the Loqate action (e.g. selectedAddressField1):

IF(
  ISBLANK({!ADDRESS_FINDER.selectedAddressField1}),
  NULL,
  IF(
    ISNUMBER({!ADDRESS_FINDER.selectedAddressField1}),
    VALUE({!ADDRESS_FINDER.selectedAddressField1}),
    NULL
  )
)

VALUE() casts the text into a number.
Blank or invalid inputs return NULL so the Flow won’t fault.

Save the resource.
In your Create/Update Records element, set the record field (e.g. MailingLatitude) to this formula resource.

Repeat the same steps for Longitude if required. Example

Loqate selectedAddressField1 → "52.123456" (Text)
Formula (latNumber) → 52.123456 (Number)
Mapped to Contact.MailingLatitude → works successfully.

Permission Sets

The Loqate for Salesforce managed package ships with four permission sets. After installing the package you assign these to your users to grant access to the address-capture components and the configuration screens. There is one administrator permission set for configuring the package, and three user permission sets that grant the read-only access end users need to capture addresses. The three user sets exist to cope with different Salesforce user license types and org-wide sharing models — you should pick the one that best matches the population of users that needs to use Loqate. You can find these in Setup → Permission Sets after the package is installed.

Loqate Administrator

Purpose: the configuration role. Assign this to anyone who needs to enter the Loqate API key, define how Loqate address fields map onto your Salesforce objects, or otherwise maintain the integration. What it grants:

Full read, create, edit, and delete access to all of the Loqate configuration objects (settings and field mappings).
Edit access to the API key field and to the mapping fields that define which Loqate address element populates which Salesforce field.
Visibility of the Loqate Address Verification app in the App Launcher.
Visibility of the Loqate Settings tab.

Who should get it: Salesforce administrators or whoever owns the Loqate integration in your org. End users should not be assigned this set — it would let them rotate the API key or change field mappings, which would break address capture for everyone else.

Loqate User (All User Types)

Purpose: the standard end-user permission set. Assign this to anyone who needs to use Loqate address capture on a Salesforce form, page, or flow. It is licence-agnostic, so it can be assigned to internal Salesforce users, Experience Cloud (Community / Partner) users, Platform users, and any other user licence type. What it grants:

Read-only access to the Loqate configuration objects so the address-capture component can resolve which fields to populate.
“View All” on the configuration records, meaning users will always see the mappings regardless of record-ownership or sharing rules.
The Loqate Address Verification app and the Loqate Settings tab are hidden — end users do not see the configuration UI.

When to choose it: this is the default end-user choice for most orgs. Pick this set if your org doesn’t have a specific policy against “View All” on custom configuration objects.

Loqate User (Restricted View All)

Purpose: the same end-user role as Loqate User (All User Types), but without “View All” on the configuration objects. Users can only see mapping and settings records that your org’s sharing rules already grant them access to. What it grants:

Read-only access to the Loqate configuration objects (same as the standard end-user set).
No “View All” — record visibility is governed by your org’s sharing model.
App and tab hidden.

When to choose it: assign this instead of the standard end-user set when:

Your org’s security policy forbids granting “View All” on custom configuration objects.
You are preparing for or maintaining a security review (e.g. AppExchange/internal audit) that flags blanket view-all permissions.
You want to intentionally scope which users can see which mapping records.

If you choose this option, make sure your sharing rules / record ownership are configured so that the relevant mapping and settings records are visible to the users who need them. If a user can’t see the mapping records, the address-capture component won’t know how to populate fields and the integration will not work for them.

Loqate User (Salesforce Users Only) — deprecated

Purpose: the original end-user permission set, retained for backwards compatibility with installations that were configured before the licence-agnostic variants were introduced. Why it’s deprecated: this set is restricted to Salesforce-licensed users only. That excludes Experience Cloud, Platform, and other licence types that many customers need to grant address-capture access to. What you should do:

New installations: do not assign this set. Use Loqate User (All User Types) or Loqate User (Restricted View All) instead.
Existing installations: continue to work. When convenient, migrate existing assignments to one of the supported sets above.

Quick decision guide

Need	Assign
Configure the package, enter the API key, edit field mappings	Loqate Administrator
Standard end user — any Salesforce licence type, no special sharing requirements	Loqate User (All User Types)
End user, but your org’s security policy disallows “View All” on configuration objects	Loqate User (Restricted View All)
Existing assignment from an older installation	Loqate User (Salesforce Users Only) — migrate to one of the two supported user sets above

How to assign a permission set

In Salesforce, go to Setup → Users → Users.
Open the user record you want to grant access to.
Under Permission Set Assignments, click Edit Assignments.
Move the relevant Loqate permission set from Available to Enabled.
Click Save.

The user will gain access at next login (or immediately, depending on session state).

Public Experience Cloud sites

If your public Experience Cloud site (formerly Community) is unable to perform address searches using the Loqate components, the issue may be caused by Salesforce’s Secure Guest User Record Access model. Even when the Loqate Settings record has external organization-wide defaults (OWD) set to Public Read Only, Salesforce enforces an additional restriction for guest users—effectively treating all objects as Private.
This means you must explicitly share the Loqate Settings record with your site’s guest user.

Configure guest access to Loqate Settings

Follow these steps to create a sharing rule that grants your guest user read access to the Loqate Settings record:

In Setup, navigate to
Sharing Settings → Loqate Settings Sharing Rules.
Click New.
Enter a Label and Rule Name of your choice.
Select Guest user access, based on criteria as the Rule Type.
Under Criteria, set:
- Field: ApiKey
- Operator: not equal to
- Value: (leave blank)
In the Share with dropdown, select your site’s guest user.
Set the Access Level to Read Only.
Click Save.

Once the sharing rule has been created and processed, guest users should be able to access the Loqate Settings record, and address searches will begin to function correctly again.

In use

With the Loqate app installed and configured, you can start using the Address finder, Email validator and Phone number validator controls when inputting addresses, email addresses and phone numbers into Salesforce. For example, here’s how the Address finder control looks during an address search:

Legacy Visualforce elements

In some cases you may want to use a more legacy approach to including Address Capture in your Salesforce instance, for example by overriding the New button action on a record listing page. In the following examples we’ll use the standard Contact record type to demonstrate the use of the included legacy Visualforce component. The Loqate app ships with a Visualforce page that can be used to replace the New button action via Object Manager, and is a reference build for the outcome of this example.

Building the page

In this example we will be creating a new page to replace the standard Contact Create page and allow for Address Capture to be used in that process. Please note that this is a legacy approach, and we would recommend you use Flow views for this kind of action.

Each of the address controls in the above screenshot are an example of the legacyLoqateAddressCapture Visualforce component. The full Visualforce page looks like this:

<apex:page lightningStylesheets="true" standardController="Contact">
    <apex:form id="form">    
        <apex:pageBlock title="New Contact">
            <apex:pageBlockSection title="Contact Info" columns="2">   
                <apex:inputText value="{!Contact.FirstName}" label="First Name"/>
                <apex:inputText value="{!Contact.LastName}" label="Last Name"/>
            </apex:pageBlockSection> 
            <apex:pageBlockSection title="Address Info" columns="2">
                <c:legacyLoqateAddressCapture label="Mailing Address" onAddressSelectedFunction="handleMailingAddressSelected" mapping="Contact Mailing" />
                <c:legacyLoqateAddressCapture label="Other Address" namespace="other" onAddressSelectedFunction="handleOtherAddressSelected" mapping="sdfghjk" />
            </apex:pageBlockSection>   
        </apex:pageBlock>
    <!-- Hidden address fields -->
        <apex:inputHidden value="{!Contact.MailingStreet}" id="street"/>
        <apex:inputHidden value="{!Contact.MailingCity}" id="city"/>
        <apex:inputHidden value="{!Contact.MailingState}" id="state"/>
        <apex:inputHidden value="{!Contact.MailingPostalCode}" id="postal"/>
        <apex:inputHidden value="{!Contact.MailingCountry}" id="country"/>
 
        <apex:inputHidden value="{!Contact.OtherStreet}" id="otherStreet"/>
        <apex:inputHidden value="{!Contact.OtherCity}" id="otherCity"/>
        <apex:inputHidden value="{!Contact.OtherState}" id="otherState"/>
        <apex:inputHidden value="{!Contact.OtherPostalCode}" id="otherPostal"/>
        <apex:inputHidden value="{!Contact.OtherCountry}" id="otherCountry"/>
 
        <apex:commandButton action="{!save}" value="Save Contact"/>
        <script>
            function handleMailingAddressSelected(address, fields) {
                console.log('Address selected:', address, fields);
                document.getElementById('{!$Component.street}').value = address.street;
                document.getElementById('{!$Component.city}').value = address.city;
                document.getElementById('{!$Component.state}').value = address.province;
                document.getElementById('{!$Component.postal}').value = address.postalCode;
                document.getElementById('{!$Component.country}').value = address.countryName;
                // You can add additional logic here to handle the address selection
            }
            function handleOtherAddressSelected(address, fields) {
                console.log('Other Address selected:', address, fields);
                document.getElementById('{!$Component.otherStreet}').value = address.street;
                document.getElementById('{!$Component.otherCity}').value = address.city;
                document.getElementById('{!$Component.otherState}').value = address.province;
                document.getElementById('{!$Component.otherPostal}').value = address.postalCode;
                document.getElementById('{!$Component.otherCountry}').value = address.countryName;
                // You can add additional logic here to handle the address selection
            }
        </script>
</apex:form>
      
</apex:page>

As you can see the controls are included like this:

<c:legacyLoqateAddressCapture label="Mailing Address" onAddressSelectedFunction="handleMailingAddressSelected" mapping="Contact Mailing" />
                <c:legacyLoqateAddressCapture label="Other Address" namespace="other" onAddressSelectedFunction="handleOtherAddressSelected" mapping="sdfghjk" />

You may need one, or as in this case multiple instances of the control for your page. The attributes for this component are as follows:

Attribute name	Description	Example
label	This is the label for the control, and will appear alongside the control input box on pages.	Mailing Address
namespace	Optional. This attribute is important when you have multiple controls on a single page, as this allows the controls to operate independently of each other. It must be unique across rendered controls.	mailing
onAddressSelectedFunction	This should be set to the name of the callback function that selected addresses will be returned to.	handleMailingAddressSelected
Mapping	Optional. If a mapping group name is provided, the second argument passed to the callback function will be an object whose keys and values are those of the mapped fields.	Contact Mailing

Let’s look in more detail at some of the aspects of the callback function and how the data gets into a record. The page itself (as well as using Lightning stylesheets to give a Lightning look and feel) uses the standard Contact controller:

<apex:page lightningStylesheets="true" standardController="Contact">

This allows it to act as a creation form for the standard Contact object. This in turn means that you can set values against the Contact records properties within the page. For the first and last name fields, this is achieved by binding the field to the FirstName and LastName fields of the controller:

<apex:inputText value="{!Contact.FirstName}" label="First Name"/>
                <apex:inputText value="{!Contact.LastName}" label="Last Name"/>

However, for the address lookups controls this is a little more involved. You can’t map directly from JS to the values, so instead you expose the properties you want to set via a selection of hidden inputs:

<apex:inputHidden value="{!Contact.MailingStreet}" id="street"/>
        <apex:inputHidden value="{!Contact.MailingCity}" id="city"/>
        <apex:inputHidden value="{!Contact.MailingState}" id="state"/>
        <apex:inputHidden value="{!Contact.MailingPostalCode}" id="postal"/>
        <apex:inputHidden value="{!Contact.MailingCountry}" id="country"/>
 
        <apex:inputHidden value="{!Contact.OtherStreet}" id="otherStreet"/>
        <apex:inputHidden value="{!Contact.OtherCity}" id="otherCity"/>
        <apex:inputHidden value="{!Contact.OtherState}" id="otherState"/>
        <apex:inputHidden value="{!Contact.OtherPostalCode}" id="otherPostal"/>
        <apex:inputHidden value="{!Contact.OtherCountry}" id="otherCountry"/>

You can then declare a callback function for each of the address lookups on the page. These fill take the address output of the lookup, and push it into the record fields defined above:

<script>
            function handleMailingAddressSelected(address, fields) {
                console.log('Address selected:', address, fields);
                document.getElementById('{!$Component.street}').value = address.street;
                document.getElementById('{!$Component.city}').value = address.city;
                document.getElementById('{!$Component.state}').value = address.province;
                document.getElementById('{!$Component.postal}').value = address.postalCode;
                document.getElementById('{!$Component.country}').value = address.countryName;
                // You can add additional logic here to handle the address selection
            }
            function handleOtherAddressSelected(address, fields) {
                console.log('Other Address selected:', address, fields);
                document.getElementById('{!$Component.otherStreet}').value = address.street;
                document.getElementById('{!$Component.otherCity}').value = address.city;
                document.getElementById('{!$Component.otherState}').value = address.province;
                document.getElementById('{!$Component.otherPostal}').value = address.postalCode;
                document.getElementById('{!$Component.otherCountry}').value = address.countryName;
                // You can add additional logic here to handle the address selection
            }
        </script>

Finally, you can add a command button that will call the Save function on the standard controller:

<apex:commandButton action="{!save}" value="Save Contact"/>

The response to this button press off a standard controller is to redirect to the record, so that flow is taken care of.

Using the page in place of the standard New view

With a Visualforce page in place that uses the Address Capture components, you now need to override the default behaviour of the New button on the contact listing page. This is achieved through the Object Manager, so navigate to Setup and search for Object Manager. Once there, select Contact from the list.

Next select Button, Links and Actions from the left-hand menu, then edit the New action – you should be able to select the new page from the Visualforce page dropdown field:

Click Save, and from now on the New action on the contact listing page will open your new page, and you can create contacts with verified addresses.

Integrations

Documentation Index

Download the Loqate app from the Salesforce AppExchange

​Setup Video

​Available services

​Use cases

​Prerequisites

​Process

​Installing the Loqate app

​Setting permissions

​App setup

​Address mappings

​Custom mappings

​Loqate widgets

​Optional: Address finder settings

​Field mappings

​Address title prefix

​Add Address Capture to Flows

​Handling Custom Field Types in Flows

​Permission Sets

​Loqate Administrator

​Loqate User (All User Types)

​Loqate User (Restricted View All)

​Loqate User (Salesforce Users Only) — deprecated

​Quick decision guide

​How to assign a permission set

​Public Experience Cloud sites

​Configure guest access to Loqate Settings

​In use

​Legacy Visualforce elements

​Building the page

​Using the page in place of the standard New view