# Google Sheets phone number checker

> Check WhatsApp, carrier, HLR and more from Google Sheets: paste our free Apps Script, check selected numbers or a whole column, or use =MV_LOOKUP().

Canonical: https://mobilevalidate.com/integrations/google-sheets · Last updated: 2026-11-08

Check phone numbers without leaving Google Sheets: paste our free script into **Extensions › Apps Script** and a **MobileValidate** menu appears. Select numbers and choose checks such as WhatsApp, carrier or HLR, or send a whole column as one bulk job at the bulk price. The results go in the columns next to your numbers. You see the maximum cost before anything runs, and inconclusive answers are free. No add-on install or marketplace account needed.

**Status:** Available

## Install the script (2 minutes)

1. Open your spreadsheet and choose **Extensions › Apps Script**.
2. Delete the sample code in `Code.gs`, then paste [the script](https://mobilevalidate.com/integrations/google-sheets/Code.gs) (or copy it from the box below).
3. Optional: click **Project Settings**, tick **Show "appsscript.json" manifest file in editor** and replace it with [our manifest](https://mobilevalidate.com/integrations/google-sheets/appsscript.json). It limits the script to the current spreadsheet and to calls to `api.mobilevalidate.com`.
4. Click **Save**, go back to the spreadsheet and reload it. The **MobileValidate** menu appears after a few seconds.
5. Choose **MobileValidate › Set API key**. Google asks you once to authorize the script: it needs to show menus and dialogs, read and write the current spreadsheet, and connect to our API.
6. Paste your key. A [free test key](https://mobilevalidate.com/get-test-key) answers the [test numbers](https://mobilevalidate.com/docs/test-values) and is never billed; a live key from the [dashboard](https://app.mobilevalidate.com) checks real numbers.

The key is saved in your own Apps Script user properties, not in a cell. People you share the spreadsheet with can't see it, and it doesn't travel with copies of the file.

## Check selected numbers

Select the cells with the numbers (a header cell at the top is fine) and choose **MobileValidate › Check selected numbers**. Type the checks, for example `whatsapp, carrier, hlr`; the script remembers your last choice. A dialog shows how many numbers will be checked and the maximum cost at the real-time price. Nothing is sent until you confirm.

The results go in the first empty columns to the right of the selection: `e164`, `number_status`, then `<check>.status`, `<check>.registered` and each attribute (for example `network.carrier.line_type`), and `checked_at`. These are the same names as the [bulk job download](https://mobilevalidate.com/docs/bulk-jobs), so the two sheets line up. Up to 500 numbers run this way, 100 per request.

Numbers should be in international format (`+44 7700 900001`). Sheets turns a typed `+447700900001` into the number 447700900001; the script adds the `+` back. For national numbers such as `07700 900001`, set a country under **MobileValidate › Set default country**.

## Check a whole column as a bulk job

Click any cell in the column with the numbers (row 1 is the header) and choose **MobileValidate › Start bulk job for this column**. The script asks for the checks and shows the free [job estimate](https://mobilevalidate.com/docs/bulk-jobs#how-do-i-estimate-a-job-first): valid, invalid and duplicate rows, the maximum cost, and any minimum per country. If you confirm, it starts one job of up to 50,000 numbers at the bulk price, with that maximum as the job's cost cap.

When the job finishes, the results are written next to each number, matched by row. An Apps Script run stops after 6 minutes; if the job takes longer, the script says so and you choose **MobileValidate › Fetch results of the last bulk job** later. The job keeps running on our side meanwhile. Rows with an empty cell are skipped.

## The =MV_LOOKUP() formula

For a handful of numbers, use the formula in a cell:

| Formula | Result |
|---|---|
| `=MV_LOOKUP(A2, "whatsapp")` | `registered`, `not registered` or `unknown` |
| `=MV_LOOKUP(A2, "carrier")` | line type and carrier, e.g. `mobile · Test Carrier` |
| `=MV_LOOKUP(A2, "carrier", "line_type")` | one attribute, e.g. `mobile` |
| `=MV_LOOKUP(A2:A50, "hlr")` | one answer per row, sent 100 numbers per request |

Limits you should know, because Google sets them for every custom function:

- **Each cell is its own call**, and Sheets may recalculate formulas when the sheet opens or the input changes. Pass a range (`A2:A50`) instead of filling the formula down, and use the menu for more than a few dozen numbers.
- **30 seconds per call.** A slow answer shows `pending (recalculate later)`.
- **Answers are cached for 6 hours** in the spreadsheet. Our API also answers a repeat within the freshness window from its cache at no charge.
- **The owner's key.** Google runs custom functions with the spreadsheet owner's stored settings, so in a shared spreadsheet `=MV_LOOKUP` uses, and bills, the owner's key. The menu commands always use the key of the person who runs them.
- **Daily quotas.** Google allows 20,000 web requests a day for a free account and 100,000 for a Google Workspace account, and may change these limits.

## Check your first list from the spreadsheet

Create a free account for a live key and free real checks, or get a test key and try the script on the test numbers first.

- [Start free (20 free real checks)](https://mobilevalidate.com/request-access)
- [Get a test key](https://mobilevalidate.com/get-test-key)
- [Open the script](https://mobilevalidate.com/integrations/google-sheets/Code.gs)

## Related

- [Bulk jobs](https://mobilevalidate.com/docs/bulk-jobs.md)
- [Real-time lookups](https://mobilevalidate.com/docs/lookups.md)
- [Test values](https://mobilevalidate.com/docs/test-values.md)
- [Excel and Google Sheets formula to format phone numbers](https://mobilevalidate.com/tools/excel-phone-number-formula.md)
- [Phone list cleaner: dedupe and normalize to E.164](https://mobilevalidate.com/tools/phone-list-cleaner.md)
- [Pricing: pay per conclusive check](https://mobilevalidate.com/pricing.md)

## Frequently asked questions

### Is there a Google Sheets add-on to install?

Not yet. The script does the same job without an add-on: you paste it into Extensions › Apps Script of the spreadsheet where you need it. You can read every line before you run it, and you don't need a Google Workspace Marketplace account.

### What does the script cost?

The script is free (MIT licence). You pay only for checks: at the real-time price for selected numbers and =MV_LOOKUP, and at the lower bulk price for a column sent as a bulk job. Inconclusive answers (unknown, unsupported country, invalid, duplicate) are not charged. See [pricing](https://mobilevalidate.com/pricing).

### Where is my API key stored?

In your Apps Script user properties, a per-user store that Google keeps for the script. It is never written to a cell, isn't visible to people you share the spreadsheet with and isn't copied with the file. **MobileValidate › Remove API key** deletes it.

### Which permissions does the script ask for?

Three: show menus and dialogs in the spreadsheet, read and write the spreadsheet it is attached to (only that one, with our manifest), and connect to an external service (only api.mobilevalidate.com, with our manifest). It doesn't read other files, your e-mail or your contacts.

### Can I try it without paying?

Yes. Set the public sandbox key or your own [free test key](https://mobilevalidate.com/get-test-key) and check the [test numbers](https://mobilevalidate.com/docs/test-values), such as +447700900001. Test keys are never billed. A new account also gets free real checks.

### Why does a formula show #ERROR!?

Hover over the cell to read the message. The usual causes are a missing key (set it from the menu), a call that took longer than Google's 30-second limit, or an API error such as insufficient balance. For long lists use the menu, which shows a clear message.

_Platform and brand names are used only to describe which service a check refers to. MobileValidate is not affiliated with, endorsed by or sponsored by any of these companies; all trademarks belong to their owners._