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 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.

Input Phone Number

Yes

String

Input phone number.

Region Code

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

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

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:

E123_INTERNATIONAL and E123_NATIONAL refer to the ITU-T Recommendation E.123 for national and international phone numbers.
INTERNATIONAL and NATIONAL use a format similar to the ITU-T Recommendation E.123 for national and international phone numbers, but use hyphens to separate blocks of numbers.
E164 refers to the ITU-T Recommendation E.164.
RFC3966 refers to the IETF 3966 RFC.

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

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.

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.