# Phone Finder

Find a phone number from an email, a company domain or a LinkedIn URL. Add direct phone numbers to contacts for calling campaigns.

**Credits:** 5 search credits when a valid phone is found (1 when searching by domain). Lookups that find nothing cost nothing. See [Pricing and limits](../pricing-and-limits).

## Inputs and options

Any one of these input combinations:

- `email` (Email address)
- `domain` (Company domain)
- `linkedin` (LinkedIn profile URL)

This tool has no options.

## Try one value

```sql
CALL TOMBA.core.phone_finder('jane.doe@acme.com');
```

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

```json
{
    "status": "found",
    "credits": 5,
    "results": [
        {
            "VALID": true,
            "E164_FORMAT": "+14155550100",
            "LINE_TYPE": "mobile",
            "CARRIER": "Example Mobile",
            "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 (EMAIL STRING);
INSERT INTO my_db.public.contacts VALUES
    ('jane.doe@acme.com');
GRANT SELECT ON TABLE my_db.public.contacts TO APPLICATION TOMBA;
```

Run the tool, then read the results:

```sql
CALL TOMBA.core.find_phones('MY_DB.PUBLIC.CONTACTS', 'EMAIL', 'CONTACTS_PHONE_FINDER', 100);

SELECT INPUT_EMAIL, VALID, E164_FORMAT, INTL_FORMAT, LINE_TYPE, CARRIER, COUNTRY_CODE
  FROM TOMBA.results.CONTACTS_PHONE_FINDER
 WHERE lookup_status = 'found';
```

Signature: `find_phones(input_table STRING, email_column STRING, output_table STRING, max_rows INT DEFAULT 100000)`

### Other inputs with `run_tool`

Company phone numbers from domains (1 credit each):

```sql
CALL TOMBA.core.run_tool('phone_finder', 'MY_DB.PUBLIC.CONTACTS', {'domain': 'WEBSITE'},
                         'CONTACTS_PHONE_FINDER_2', 100, {});
```

<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

- 5 credits when a valid phone is found by email or LinkedIn URL; 1 credit when searching by company domain.
- The table procedure takes an email column. For domains or LinkedIn URLs, use `run_tool` with `{'domain': ...}` or `{'linkedin': ...}`.

## Related

- [Phone Validator](./phone-validator)
- [Email Finder](./email-finder)