Semarchy Phone enricher

The Semarchy Phone enricher standardizes and improves phone number formatting.

Plugin ID

Semarchy Phone Enricher - com.semarchy.engine.plugins.convergence.phone

Description

This enricher accepts either an international phone number with the international prefix or a national phone number with a region code as input. It returns a standardized enriched phone number in the enriched phone format, along with geocoding data that may include the country, region or state, and city name, depending on the country.

If a phone number is not valid, the enricher returns the original phone value as the enriched phone number, a status code, as well as a status text describing the issue with the input phone number.

This plugin is thread-safe and supports parallel execution.

Plugin parameters

This plugin does not use any parameter.

Plugin inputs

The following table lists the plugin inputs.

Input name Mandatory Type Description

Input Phone Number

Yes

String

Input phone number.

Region Code

No

String

Two-letter region code for a national phone number, according to the ISO 3166-1 standard. If this parameter is left empty, the phone number provided in Input Phone Number should include the international country calling code.

Enriched Phone Format

No

String

Format of the enriched phone number. Possible values are INTERNATIONAL (default), NATIONAL, E123_INTERNATIONAL, E123_NATIONAL, E164, and RFC3966. For more information, see Phone formats.

Region of Origin

No

String

Formats the phone output for international dialing from the country or region provided in this input (e.g., US, FR, GB, DE). Use ZZ for an unknown region. For the complete list of country codes, visit countrycode.org.

Phone formats

The following standards are supported to format the enriched phone number:

Phone format examples
  • E123_NATIONAL (E.123 - National notation): (042) 123 4594

  • E123_INTERNATIONAL (E.123 - International notation): +31 42 123 4567

  • NATIONAL (E.123 - National notation with hyphens): (042) 123-4594

  • INTERNATIONAL (E.123 - International notation with hyphens): +31 42-123-4567

  • E.164 (E.164 - International notation): +31421234567 (equivalent to E.123 with no formatting)

  • RFC3966 (RFC3966 - International notation): +31-42-123-4567 (equivalent to E.123 with hyphens instead of spaces)

Plugin outputs

The following table lists the plugin outputs.

Output name Type Description

Enriched Phone Number

String

Phone number returned by the enricher in the format specified in the Enriched Phone Format input field. This string is null if the enricher was not able to process the input phone number. The status code and status text help troubleshoot such issues.

Geocoding Data

String

Geocoding data computed for a given number and country. Depending on the country and phone number, this value includes the country, region or state, and city information. This string is null if the enricher was not able to process the input phone number. The status code and status text help troubleshoot such issues.

Status Code

String

Return code for the phone number processing. For more information, see Status codes.

Status Text

String

Text explaining the status code.

International Phone Prefix

String

International phone prefix for worldwide dialing.

National Number

String

National number part of a phone number in International format. It is often the International number without the country prefix.

Extension

String

Extension part of the phone number.

Country Code Source

String

Explains how the country code was retrieved. Possible values are FROM_NUMBER_WITH_PLUS_SIGN, FROM_NUMBER_WITH_IDD, FROM_NUMBER_WITHOUT_PLUS_SIGN and FROM_DEFAULT_COUNTRY.

Leading Zero

String

Returns 0 or 1 to specify if leading zero is mandatory for foreign calls.

Possible Phone Number

String

Returns 0 or 1 to indicate whether a phone number is a possible number and the region where the number could be dialed from.

Possible Phone Number Reason

String

Detailed explanation of why a phone number is a possible number or not. Possible values are INVALID_COUNTRY_CODE, IS_POSSIBLE, TOO_LONG, and TOO_SHORT.

Valid Phone Number

String

Returns 0 or 1 to indicate whether a phone number matches a valid pattern.

Valid Phone Number For Region

String

Returns 0 or 1 to indicate that a phone number is valid for the specified region code.

Phone Line Type

String

Provides the line type of a phone number. Possible values are FIXED_LINE, FIXED_LINE_OR_MOBILE, MOBILE, PAGER, PERSONAL_NUMBER, PREMIUM_RATE, SHARED_COST, TOLL_FREE, UAN, UNKNOWN, and VOIP.

Region Code

String

Returns the region code for the phone number. For the complete list of country codes, visit countrycode.org.

International Phone Number

String

Phone number formatted for international dialing.

Timezones

String

List of corresponding timezones for a given number (e.g., Europe/Paris). If the timezone is unknown, returns Etc/Unknown.

First Timezone

String

First timezone from the list of corresponding timezones for a given number.

Carrier Name

String

Name of the carrier for the phone number.

Status codes

The following status codes are returned by the enricher:

  • 0 - OK: optimal execution; no error has been detected.

  • 1 - INPUT_WAS_NULL: the input phone number was not set.

  • 2 - PARSING FAILED: the string supplied does not seem to be a phone number; review the status text for more information.