Documentation - Phone Verification Javascript Reference

The phone verification API is currently in a beta state. It can be used in production but may be adjusted and improved. Please let us know if you wish to use the service so that we can keep you up-to-date on any changes being made.

AddressfinderPhone.Phone.Widget class

This widget adds phone verification to a simple form field. It will check that the phone number is valid and meets the configured criteria. If unverified, a cross icon and error message (optional) are displayed. A verified phone number is identified with a simple tick icon.

You can choose from block, warn or allow behaviour for each of the three types of phone addresses. These include:

nonMobile phone numbers, such as the landline number 09 123 4567
countryNotAllowed. When a phone number might be valid but comes from a country you wish to exclude.
Unverified phone number.

More information about how to configure these options and changing the visual styles can be found on the advanced options page. The code examples page demonstrates many of these configuration options.

Constructor

Parameter	Type	Description	Example
`phoneSelector`	`String`	CSS selector for one or more input elements.	`input.phone_number`
`licenceKey`	`String`	Your unique licence key (find on Portal credentials)	`VYT6FHV6TPQEWNBG4K7Q`
`defaultCountryCode`	`String`	Set the default country code	`NZ`
`options`	`Object`	Configuration options, see the Options section below.	`{"rules": {"unverified": "block", "message": "Phone number not verified."}}`

Methods

Method	Parameters	Description
`disable()`		Disables the Addressfinder phone widget. The verification function will stop working until the widget is re-enabled.
`enable()`		Re-enables a disabled Addressfinder phone widget.
`reactivate()`		Executes the verification function on the input value. The Addressfinder phone widget must be enabled.
`setDefaultCountryCode()`	`country_code:String`	Set the default country to verify phone numbers against after the Addressfinder phone widget has been initialised.

Options

Key	Type	Description	Default
`rules.unverified.rule`	`String`	Rule for unverified phone addresses: `block`, `warn` or `allow`	`block`
`rules.unverified.message`	`String`	Message to display to the user when an unverified phone number is detected.	Phone number not verified.
`rules.countryNotAllowed.rule`	`String`	Rule for phone numbers coming from a country you wish to exclude: `block`, `warn` or `allow`.	`block`
`rules.countryNotAllowed.message`	`String`	Message to display to the user when a phone number from a country you wish to exclude is detected.	Allowed countries: list of allowed country names.(Set through allowedCountryCodes
`rules.nonMobile.rule`	`String`	Rule for non mobile phone number: `block`, `warn` or `allow`.	`allow`
`rules.nonMobile.message`	`String`	Message to display to the user when a non mobile phone number is detected.	-
`countrySelect`	`String`	CSS selector for the country selector.	-
`container`	`DOM element`	Element into which the loading indicators and error messages are injected.	-
`allowedCountryCodes`	`String`	List of ALPHA-2 country codes you accept a phone number to come from. Separated by a comma, eg `AU,NZ`	-
`timeout`	`Integer`	How long the API should run before returning an indeterminate connection status.	10
`countryMappings`	`object`	Ability to map HTML select values to a ALPHA-2 country code. View a code example.	Eg: countryMappings: { "AUS" : "AU" }

Events

Event	Callback Arguments	Description
`result:verified`	`metadata:Object`	Fired when the widget receives a response from the API that aligns with the permissions (`allow`, `warn`, `block`) defined in the widget's rules. e.g. Phone number is verified.
`result:not_verified`	`metadata:Object`	Fired when the widget receives a response from the API that conflicts with the permissions (`allow`, `warn`, `block`) defined in the widget's rules. e.g. Country not allowed.

Metadata

Property	Type	Description	Example
`is_verified`	`Boolean`	Indicates if the phone number is verified.	true
`line_type`	`String`	The type of phone line the number is connected to.	mobile
`line_status`	`String`	The connection status of the supplied number.	connected
`line_status_reason`	`String`	Insights of the line_status result.	timeout
`country_code`	`String`	The two character ISO code of the country of the phone number.	AU
`calling_code`	`String`	The country calling code of the phone number.	61
`raw_national`	`String`	The national phone number without any whitespace or punctuation.	0285038000
`formatted_national`	`String`	The formatted national phone number including country-specific whitespace and punctuation.	(02) 8503 8000
`raw_international`	`String`	The international phone number in E.164 format.	+61285038000
`formatted_international`	`String`	The formatted international phone number including country-specific whitespace.	+61 2 8503 8000
`not_verified_code`	`String`		`INVALID_FORMAT`
`not_verified_reason`	`String`	A code indicating why the number did not verify.	Phone number format is incorrect
`success`	`Boolean`	If the number did not verify, this will contain a short description of the failure reason.	true