# Phone Validator

Validate and format a phone number (line type, carrier, region). Check and normalize the phone numbers you already have: valid or not, line type, carrier, E.164 format.

**Credits:** 1 search credit per validation. Lookups that find nothing cost nothing. See [Pricing and limits](../pricing-and-limits).

## Inputs and options

Input: `phone` (Phone number)

Optional: `country_code` (Country code (ISO-2, optional)).

This tool has no options.

## Try one value

```sql
CALL TOMBA.core.phone_validator('+1 415 555 0100', 'US');
```

The call returns the result as a `VARIANT` (example values, shortened):

```json
{
    "status": "found",
    "credits": 1,
    "results": [
        {
            "VALID": true,
            "E164_FORMAT": "+14155550100",
            "LINE_TYPE": "fixed_line",
            "REGION": "California"
        }
    ]
}
```

`status` is `found`, `not_found`, `invalid` or `error`; `results` holds the output columns and `data` the complete
Tomba record.

## Run it over a table

Create a small table to try it (or use one of yours, after [granting the app access](../installation#3-let-the-app-read-your-tables)):

```sql
CREATE OR REPLACE TABLE my_db.public.contacts (PHONE STRING, COUNTRY STRING);
INSERT INTO my_db.public.contacts VALUES
    ('+1 415 555 0100', 'US'),
    ('030 1234567', 'DE');
GRANT SELECT ON TABLE my_db.public.contacts TO APPLICATION TOMBA;
```

Run the tool, then read the results:

```sql
CALL TOMBA.core.validate_phones('MY_DB.PUBLIC.CONTACTS', 'PHONE', 'CONTACTS_PHONE_VALIDATOR', 100, 'COUNTRY');

SELECT INPUT_PHONE, VALID, E164_FORMAT, INTL_FORMAT, LINE_TYPE, CARRIER, REGION
  FROM TOMBA.results.CONTACTS_PHONE_VALIDATOR
 WHERE lookup_status = 'found';
```

Signature: `validate_phones(input_table STRING, phone_column STRING, output_table STRING, max_rows INT DEFAULT 100000, country_code_column STRING DEFAULT '')`

<Callout type="tip">
    Start with a small `max_rows` (like 100) to check the match rate on your
    data, then run the whole table, in the [background](../background-runs) if
    it is large.
</Callout>

## Output columns

Each row starts with `INPUT_<name>` columns (your values, unchanged) and then has:

`VALID`, `E164_FORMAT`, `INTL_FORMAT`, `LOCAL_FORMAT`, `COUNTRY_CODE`, `LINE_TYPE`, `CARRIER`, `REGION`, `TIMEZONES`, followed by the [common columns](../reference/output-columns)
(`LOOKUP_STATUS`, `CREDITS`, `DATA`, `SOURCE`, …).

## Tips

- The country column is optional but helps with local-format numbers (`030 1234567`). It takes a **column name**, not a value like `'US'`.
- Store `E164_FORMAT` in your CRM: it is the standard international format.

## Related

- [Phone Finder](./phone-finder)