Phone Numbers

Filter

This filter identifies phone and fax numbers such as (304) 555-5555, 304-555-5555, and 1-800-123-4567 in text.

How Phone Numbers Are Detected

Detection uses libphonenumber with its possible number check, once for each configured region. A possible number has a plausible length for its country; it does not have to be a valid, assigned number. This means the filter finds phone-formatted numbers that could not be dialed, such as (112) 997-5633, whose area code begins with 1 and so is not a valid North American number. Text that is not phone-formatted but has a possible length, such as 1-12-2020, may also be found. Detection is probabilistic, so validate the filter's output against your own data.

Without a +, libphonenumber reads a leading 1 as the North American country code and then reads an area code's leading 1 as a national prefix, which leaves too few digits for a possible number. So that a number's punctuation does not decide whether it is found, when a configured region uses country code 1 (such as US or CA) the filter also reads a bare 1 country code followed by a separator as +1. With this, 1-112-997-5633, 1 112 997 5633, 1.112.997.5633, and 1-109-299-5128 x512 are found, as +1 112-997-5633 is. A number written with no separators, such as 11129975633, is not found. A number already found without this reading, such as 112-997-5633 in Item 1 112-997-5633, is unchanged.

Required Parameters

This filter has no required parameters.

Optional Parameters

Parameter	Description	Default Value
phoneNumberFilterStrategies	A list of filter strategies.	None
region	Default region(s), ISO 3166-1 alpha-2 (for example "US", "GB", "FR"), used to interpret phone numbers written without an international + country code. A string sets a single region; an array enables detection for each listed region, and the merged results are de-duplicated. Numbers with a + prefix are detected regardless of this value.	"US"
leniency	libphonenumber matching strictness: POSSIBLE, VALID, STRICT_GROUPING, or EXACT_GROUPING.	"POSSIBLE"
enabled	When set to false, the filter will be disabled and not applied	true
ignored	A list of terms to be ignored by the filter.	None
windowSize	Sets the size of the window (in terms) surrounding a span to look for contextual terms. If set, this value overrides the value of span.window.size in the configuration.	The value of span.window.size which is by default 5.
priority	The priority (integer) of this filter. Valid values are any positive integer, where a higher value indicates a higher priority. Priority is used for tie-breaking when two spans may be otherwise identical.	0

Filter Strategies

The filter may have zero or more filter strategies. When no filter strategy is given the default strategy of REDACT is used. When multiple filter strategies are given the filter strategies will be applied in order as they are listed. See Filter Strategies for details.

Strategy	Description
REDACT	Replace the sensitive text with a placeholder.
MASK	Replace each character of the sensitive text with a mask character (* by default).
TRUNCATE	Replace all but a few characters of the sensitive text with a truncation character (* by default).
RANDOM_REPLACE	Replace the sensitive text with a similar, random value.
STATIC_REPLACE	Replace the sensitive text with a given value.
CRYPTO_REPLACE	Replace the sensitive text with its encrypted value.
HASH_SHA256_REPLACE	Replace the sensitive text with its SHA256 hash value.
FPE_ENCRYPT_REPLACE	Replace the sensitive text with a value generated by format-preserving encryption (FPE)
LAST_4	Replace the sensitive text with just the last four characters of the text.

Conditions

Each filter strategy may have one condition. See Conditions for details.

Conditional	Description	Operators
TOKEN	Compares the value of the sensitive text.	==, !=, startswith
CONTEXT	Compares the filtering context.	== , !=
CONFIDENCE	Compares the confidence in the sensitive text against a threshold value.	< , <=, > , >=, ==, !=

Example Policy

{
   "identifiers": {
      "phoneNumber": {
         "phoneNumberFilterStrategies": [
            {
               "strategy": "REDACT",
               "redactionFormat": "{{{REDACTED-%t}}}"
            }
         ]
      }
   }     
}

To detect national-format numbers from regions other than the United States, set region to a single ISO 3166-1 alpha-2 code or an array of them:

{
   "identifiers": {
      "phoneNumber": {
         "region": ["US", "GB", "FR"],
         "phoneNumberFilterStrategies": [
            {
               "strategy": "REDACT"
            }
         ]
      }
   }
}

The region property requires redaction policy schema 1.2.0.

Requiring valid phone numbers

Set leniency to VALID to reject candidates that are merely possible, such as short numeric identifiers or years that can be detected under some regions:

{
  "identifiers": {
    "phoneNumber": {
      "region": ["US", "GB", "DE"],
      "leniency": "VALID"
    }
  }
}

Omitting leniency retains the default POSSIBLE behavior. Values are case-sensitive; unknown values fail policy preparation. STRICT_GROUPING and EXACT_GROUPING additionally constrain number formatting. Validity follows numbering-plan rules; it does not establish whether a number is assigned or in service, or whether a valid-looking number is a phone number in context. Confidence conditions remain independent of this candidate-validation setting.

Java callers can use phoneNumber.setLeniency(PhoneNumberUtil.Leniency.VALID).

The leniency property requires redaction policy schema 1.3.0 as bundled with PhiSQL 1.6.0 or later.