Skip to main content

Phone Verification Widget options

List of common widget configurations and associated code examples for Addressfinder phone verification.

Configuration options

Default country code

The Phone Verification service needs to know which country to attempt to check against when attempting to verify the supplied phone number. This is a mandatory requirement so in the event that the supplied number does not include an international calling code the default country code is applied. The default country code needs to be supplied as a 2-digit Iso country code. Eg. defaultCountryCode: "AU",

Allowed Countries

The third step in the Phone Verification process is to check the verified number against the rules (supplied or default). To enforce the optional countryNotAllowed rule, a 2-digit Iso country code (or comma seperated list of codes) needs to be included in the widget code. Eg. allowedCountryCodes: "AU, US, GB, CA, NZ",

Using a country select field

The widget can be configured to watch a country select field and use the selected country as part of the verification process. When a country is selected, it’s applied as the defaultCountryCode, allowing the widget to correctly interpret and verify locally formatted numbers — even if they don’t include an international calling code.

This is especially useful on forms that collect phone numbers from users in different countries. It improves the verification success rate and makes the experience easier for users, since they don’t need to enter full international numbers.

View this code example demonstrating the use of the country select field.

Setting the timeout

The processing time of the Phone Verification service can vary and is not always fast. To ensure a smooth user experience, you can set a timeout in the widget code. This timeout will stop the verification process at the defined time and return a response with all information gathered up to that point. In most cases, the only detail missing when a timeout occurs is the line_status.

By default, the timeout is set to 10 seconds.

Setting rules

In the Phone Verification service, each phone number is checked for three main attributes: the country it’s registered in, the line type, and the connection status. These are detected during the verification process and used by the widget to apply the rules you’ve set.

The options relating to these attributes are:

  • countryNotAllowed
  • nonMobile
  • unverified

For each number, you can choose to allow, warn, or block it based on the rules you’ve set. The widget will then show the appropriate icon and message to match your choice.

  • allow: Shows a green tick without any error message.
  • warn: Displays an orange warning icon and an accompanying error message.
  • block: Presents a red cross, an error message, and prevents form submission.

Key rule configuration notes

  • Removing a rule will result in the default rule being applied.
  • Removing the message line will result in the default message being displayed when the rule is enforced.
  • Setting message: false will result in no message being displayed when the rule is enforced.

Custom styling

Our Javascript widget includes a stylesheet that defines the visual aspects of the icons and messages that are displayed. You may decide to adjust the colours or fonts used to more closely match the branding of the page in which the widget is embedded. This can be done easily by overriding the default styles that are included in the file.

You can inspect the styles here (tip: use an online beautifier to make it easier to read) and then define your own CSS rules to override the default styles.

View a code example, where we use the Phone Widget with a different colour for the message.

Here is an example of the html elements that are included in the DOM:

<span class="af-pv-icon-block af-pv-icon" style="top: 768.943px; left: 632.458px; height: 26.5px; width: 26.5px;"></span>
<span class="af-pv-message" aria-live="polite" style="left: 270px; top: 811.484px; width: 400px; display: inline-block;">It looks like there could be a problem with this phone number. You must enter a correct phone number</span>

Working inside a modal

Because modals are usually static in the context of the page, it is recommended when initialising the widget to provide a Node to the container option. This option takes an HTML Node that will be used as a basis for the HTML injected by the widget. As such, positioning of our loading indicator and feedback message to the user will still work as expected. An example of how to use the container option can be found here.