# PHONE\_VALID

### Description

`PHONE_VALID` checks whether a string is a valid phone number using [Google's libphonenumber](https://github.com/google/libphonenumber). It performs two checks in sequence:

1. **Possible number** — is the length plausible for any phone number in that country?
2. **Valid number** — does the number match a known number range or pattern for that country?

A number that passes the length check but does not match a known range returns `false`. A number that cannot be parsed at all returns `unknown`.

The input string may contain spaces, dashes, or parentheses — these are handled by the parser. A leading `00` is treated as an international dialling prefix, equivalent to `+`.

If the number does not start with `+` or `00`, a `country_code` must be provided to interpret it as a local number. Without one, the result is `unknown`.

### Syntax

```
PHONE_VALID(phone, country_code?)
```

**Returns:** `true` if the number is valid, `false` if it is structurally invalid, `unknown` if the input cannot be parsed (e.g. empty string, unrecognised country code, no country context for a local number).

### What counts as valid?

libphonenumber validates both number length and whether the number falls within a known range for the country. This means:

* `+41791234567` → `true` — valid Swiss mobile number
* `+41791234` → `false` — too short to be a valid Swiss number
* `+41999999999` → `false` — correct length but not a valid Swiss number range
* `0041123` → `false` — the `00` prefix is treated as `+`, making it `+41123`, which is too short
* `+99999999999` → `unknown` — unrecognised country calling code; the parser throws a parse exception rather than returning a structural result

### Examples — Switzerland (`CH`, +41)

```
PHONE_VALID('+41791234567')
```

Returns `true` — valid Swiss mobile number in international format.

```
PHONE_VALID('0041791234567')
```

Returns `true` — `00` is treated as `+`, equivalent to `+41791234567`.

```
PHONE_VALID('0791234567', 'CH')
```

Returns `true` — valid Swiss mobile number in local format.

```
PHONE_VALID('+41791234')
```

Returns `false` — too short to be a valid Swiss number (only 7 digits after the country code, Swiss numbers require 9).

```
PHONE_VALID('+41999999999')
```

Returns `false` — length is plausible, but the number does not fall within any known Swiss number range.

```
PHONE_VALID('079123', 'CH')
```

Returns `false` — too short.

### Examples — Germany (`DE`, +49)

```
PHONE_VALID('+4915123456789')
```

Returns `true` — valid German mobile number (Telekom range).

```
PHONE_VALID('015123456789', 'DE')
```

Returns `true` — valid German mobile number in local format.

```
PHONE_VALID('+493012345678')
```

Returns `true` — valid Berlin landline.

```
PHONE_VALID('+491234')
```

Returns `false` — too short.

```
PHONE_VALID('+4919999999999')
```

Returns `false` — does not match a known German number range.

### Examples — United Kingdom (`GB`, +44)

```
PHONE_VALID('+447911123456')
```

Returns `true` — valid UK mobile number.

```
PHONE_VALID('07911123456', 'GB')
```

Returns `true` — valid UK mobile number in local format.

```
PHONE_VALID('+442071234567')
```

Returns `true` — valid London landline.

```
PHONE_VALID('+44791112')
```

Returns `false` — too short.

```
PHONE_VALID('+44099999999')
```

Returns `false` — does not match a known UK number range.

### Edge cases

```
PHONE_VALID('0791234567', 'XX')
```

Returns `unknown` — `'XX'` is not a recognised country code.

```
PHONE_VALID('0791234567')
```

Returns `unknown` — no country context to interpret the local number.

```
PHONE_VALID('+99999999999')
```

Returns `unknown` — `+999` is not a recognised country calling code, so the parser throws a parse exception and cannot return a structural result.

### Example in context

```
p is Person
PHONE_VALID(p.mobile_number, 'CH')
```

Returns `true` if the entered number is a valid Swiss phone number or a valid internationally prefixed number. Commonly used to validate phone inputs before allowing case progression.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.atfinity.io/rule-language/operators/special-operators/phone_valid.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.