Search and Select Address Verification Actions¶
Overview¶
AddressTools provides two Apex actions that find and verify an address without a record page or any AddressTools screen component: Search Address and Select Address. Search Address takes free text and returns matching candidates. Select Address resolves a chosen candidate into a full verified address, returned as individual fields.
The actions are available wherever Salesforce offers Apex actions, including Flow Builder and Agentforce. Neither action writes to a record. The verified address is returned to the caller, which decides what to do with it, for example updating a record in a later flow element. For the Agentforce configuration, see Use the Address Actions in an Agentforce Agent.
Before You Start¶
- AddressTools must be installed and connected with an authentication token. See Create an Authentication Token.
- The user running the action needs Apex class access to the two AddressTools Apex classes behind the actions. The AddressTools Premium Standard User Permission Set includes it, and the AddressTools Premium Agent User Permission Set grants it to Agentforce agent users. See Grant Access to the Actions.
How the Actions Work Together¶
- Call Search Address with the text to search for. It returns a list of candidates.
- Check each candidate's Is Container value. A candidate whose value is false is an address that can be selected. A candidate whose value is true is a group of addresses, such as a street or a building with many units.
- To narrow a container, call Search Address again with the container's Candidate Id as Container Id and the same Search Text. Repeat until the candidates are addresses.
- Call Select Address with the chosen candidate's Candidate Id as Address Id and its Search Context as Search Context. It returns the verified address.
Both actions report problems through their Success and Message outputs rather than failing the flow or conversation, so the caller can show the message and try again.
Note
A failure message usually ends with a trace ID. If you contact support about a failure, include it so they can find the request.
Billing¶
Each successful Select Address call consumes one verification lookup. Search Address calls do not consume lookups, so a search can be refined as many times as needed before an address is selected. Your remaining lookups are shown on the Licensing & Lookups tab of AddressTools Administration.
Grant Access to the Actions¶
The AddressTools Permission Sets match user roles. The AddressTools Premium Standard User Permission Set includes class access to the actions, so users who already work with AddressTools need nothing further. The AddressTools Premium Admin User Permission Set does not include the actions: it is for administrators who configure AddressTools rather than use it.
For an Agentforce agent user, AddressTools includes the AddressTools Premium Agent User Permission Set. It grants Apex class access to the two Apex classes behind the actions and nothing else: no user license, Visualforce pages or tabs, so it can be assigned to a user on the Einstein Agent license.
- Navigate to Setup > Permission Sets and click AddressTools Premium Agent User.
- Click Manage Assignments, then Add Assignment.
- Select the users, click Next, then click Assign.
Use the Actions in Flow Builder¶
A screen flow that collects an address follows the sequence above:
- Add an Action element, search for and select the Search Address action, and set Search Text from a text input on an earlier screen. Leave Allowed country codes and Preferred country code blank to search every country, or set them to restrict or bias the search.
- Check the Success output with a Decision element. When it is false, show the Message output and return to the input screen.
- Present the Candidates output on a Screen element for the user to choose from, showing each candidate's Candidate Text, and its Candidate Description when present. Use a Loop element to build the choices, or a component that accepts a collection.
- When the chosen candidate's Is Container value is true, call Search Address again with its Candidate Id as Container Id and show the new candidates. Repeat until an address is chosen.
- Add a second Action element for Select Address, with Address Id set to the chosen candidate's Candidate Id and Search Context set to the same candidate's Search Context.
- Use the outputs of Select Address, for example in an Update Records element that writes them to the record's address fields.
Action Reference¶
Search Address¶
Inputs:
| Input | Required | Description |
|---|---|---|
| Search Text | Yes | The address text to search for, for example 10 Downing Street London. Partial input is expected. |
| Allowed country codes | No | Comma-separated two-letter ISO country codes that restrict the search, for example US,GB,FR. Codes that are not AddressTools countries are ignored and reported in Message. Leave blank to search globally. |
| Preferred country code | No | A two-letter ISO country code, for example US. Biases the results towards this country without restricting them. |
| Container Id | No | The Candidate Id of a container from a previous result, to search inside it. Leave blank for a new search. |
Outputs:
| Output | Description |
|---|---|
| Success | True when the search completed. False when it failed; see Message for the reason. |
| Message | A summary of the search outcome, including any country codes that were ignored, or the reason for a failure. |
| Candidates | The matching candidates, in the order ranked by the address service. |
| Candidate Count | The number of candidates returned. |
Each candidate carries these values:
| Value | Description |
|---|---|
| Candidate Id | Identifier for the candidate. Pass it to Select Address as Address Id, or back to Search Address as Container Id. |
| Candidate Text | The display text: the full single-line address, or the group name for a container. |
| Candidate Description | Additional context when the service supplies it. Containers report how many addresses they hold, for example " - 4 Addresses"; address candidates usually have none. |
| Candidate Type | The type reported by the address service. Address means the candidate can be selected; any other value means it is a container. |
| Is Container | True when the candidate groups further results and must be searched into. False when it can be passed to Select Address. |
| Search Context | Context for the search that produced the candidate. Pass it unchanged to Select Address alongside the Candidate Id. |
Select Address¶
Inputs:
| Input | Required | Description |
|---|---|---|
| Address Id | Yes | The Candidate Id of a Search Address result whose Is Container value is false. |
| Search Context | No | The Search Context from the same candidate. Always pass it through unchanged. |
Outputs:
| Output | Description |
|---|---|
| Success | True when the address was resolved. False when it failed; see Message for the reason. |
| Message | The outcome, or the reason for a failure. |
| Organisation name | Organisation or company name. |
| Sub-building name | Flat, unit or other sub-building name. |
| Building name | Building name. |
| Building number | Building or premise number. |
| Dependent thoroughfare (secondary street) | Secondary or dependent street name. |
| Thoroughfare (street) | Street name only, for example High Street. |
| Dependent locality | Dependent locality or district. |
| Post town | Post town or city. |
| Postcode | Postcode or ZIP Code. |
| Administrative area (county) | Administrative county or equivalent area. |
| State / province | Largest administrative division, for example a US state or Canadian province. Empty when it duplicates the city for a country where a state is not mandatory. |
| Country name | The country name as configured in AddressTools, honouring alternative country name mappings. Contains the two-letter ISO code when no country matches. |
| Country code (ISO-2) | Upper-case two-letter ISO country code, for example GB or US. |
| Formatted street | The complete street address line, for example 10 High Street. May contain more than one line. |
| Latitude | Latitude of the address, when geocoding is enabled. |
| Longitude | Longitude of the address, when geocoding is enabled. |
| Geocode accuracy | Reserved for future use. |
| Property use | Address-use classification, for example Residential, Commercial or Mixed. |
| Formatted address label | The complete address, formatted to the country's postal specification. |
Good to Know¶
- Both actions report problems through Success and Message rather than stopping the flow or conversation.
- Nothing is saved. To store the verified address on a record, use the outputs of Select Address in a later element of your own.
- A container candidate, such as a street or a building with many units, cannot be selected directly. Narrow it by calling Search Address again with the container's Candidate Id as Container Id.
- Search Context describes the search that produced a candidate. Pass it unchanged to Select Address so the address service records which search the selected address came from.
- Country codes are checked against the countries installed in AddressTools. An unrecognised code in Allowed country codes is ignored and reported in Message; if no code in the list is recognised, the search fails rather than searching every country. A Preferred country code that is not a two-letter code is reported in Message but does not stop the search.