Search and Select Address 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.
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. A failure message ends with a trace ID, except the message reporting that too many addresses were searched or resolved in one transaction, which is produced before any request is made; see Trace IDs.
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.
Security Classification¶
Salesforce requires custom agent actions in a managed package to be classified by the type of agent they are intended for and by whether they return public or nonpublic data.
- Agent type: both actions are suitable for employee-facing agents and for service agents.
- Data: both actions are public. They return postal address data from the AddressTools verification service, which is public information. They do not read or change records in your org; the only org data they touch is the country reference data installed with AddressTools and the package's own authentication token.
No user verification is required before an agent calls the actions, and their outputs contain no data from your org.
Use the Actions in Flow Builder¶
A screen flow that captures 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.
Each Search Address or Select Address call is one request to the AddressTools verification service. The actions accept a collection of requests, so a flow that runs on many records at once does not exceed Salesforce callout limits; a request that cannot be sent within the limits of one transaction returns Success as false with a message asking for a smaller batch.
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 ending with a trace ID. |
| 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 ending with a trace ID. |
| 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.