# Phone Number Validator and Formatter: E.164, Carrier, Line Type (`transparent_meteorite/phone-number-validator-formatter`) Actor

Validate and format phone numbers in bulk, offline, with Google libphonenumber: E.164, national and international formats, carrier, line type, country and time zones. No key, no network lookup.

- **URL**: https://apify.com/transparent_meteorite/phone-number-validator-formatter.md
- **Developed by:** [Detroit Web Agent - Open Data](https://apify.com/transparent_meteorite) (community)
- **Categories:** Developer tools, Lead generation, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.54 / 1,000 number checkeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Phone Number Validator and Formatter: E.164, Carrier, Line Type

Use this to clean and validate a list of phone numbers in bulk. Paste numbers in any common format, optionally add a default country, and get one row per number with validity, E.164 / national / international / RFC 3966 formats, country, region, carrier name (where the data has it), line type, time zones and a plain-English error reason when the number is wrong.

It runs on Google's open-source **libphonenumber** metadata, the same engine behind Android and many CRMs, entirely offline inside the Actor. No API key, no login, no proxy, and no call to any phone network.

### Run in 30 seconds

1. Open the **Input** tab. The prefilled list (14 numbers from 11 countries, plus two deliberately bad ones) is a ready-to-run test.
2. Click **Start**. The run normally finishes in under 10 seconds.
3. Open the **Numbers** table in the Output tab, or download the dataset as JSON, CSV, Excel or HTML.
4. Replace the list with yours, set **Default country** for numbers written without a `+`, and run again.

### What does this Actor do?

For every number you send, the Actor parses it against the country you name (or the `+` country code), checks it against libphonenumber's numbering-plan rules and returns a flat, spreadsheet-ready row:

| Group | Fields |
|---|---|
| Verdict | `status` (`valid`, `possible_but_invalid`, `invalid`, `unparseable`), `isValid`, `isPossible`, `possibilityReason` |
| Formats | `e164`, `international`, `national`, `rfc3966`, `outOfCountry` (how to dial it from your default country) |
| Place | `countryCallingCode`, `regionCode` (ISO 3166 alpha-2), `countryName`, `location` (city or region description), `timeZones` |
| Line | `lineType` (mobile, fixed_line, fixed_line_or_mobile, toll_free, premium_rate, shared_cost, voip, personal_number, pager, uan, voicemail), `isMobile`, `isGeographic` |
| Carrier | `carrier`, plus `carrierNote` that says exactly what the carrier value means or why it is empty |
| Parts | `nationalNumber`, `extension` |
| Errors | `errorCode`, `errorReason` for every number that is not valid |

26 fields per number, all in one dataset schema, with `null` rather than a missing key for anything that does not apply.

### Limits: offline validation, not a live line check

This Actor does **not** ping the number, send an SMS, run an HLR (Home Location Register) lookup or ask any carrier whether a SIM is active. It tells you whether a number is **well-formed and allocated in the numbering plan**, not whether someone will pick up. That has two consequences, and we think both are features:

- **Privacy.** Nobody is contacted and the numbers you check never leave the Actor, so there is no third-party lookup service seeing your customer list and no ping that could alert the person behind the number. That makes it suitable for pre-checking CRM exports, sign-up forms and lead lists in a way live lookups are not.
- **Price and speed.** No network round trip per number means a flat price of a fraction of a cent, thousands of numbers per second, and no rate limits or per-lookup provider fees.

If you need to know whether a mobile number is currently reachable or roaming, you need an HLR provider. Use this Actor first to throw out the numbers that are malformed or the wrong length, so you pay an HLR provider only for the survivors.

Other limits: up to 5,000,000 numbers per run (the **Max numbers** setting), and the data is only as current as the libphonenumber release bundled in the Actor, so numbers allocated very recently may show as invalid until the Actor is rebuilt with newer metadata.

#### What "carrier" means here

libphonenumber stores the **original** carrier for number ranges, and only for countries where that data is published (largely mobile ranges, for example the UK, France, Germany, India, Brazil, Japan and many more; the US and Canada have none because of number portability). When a number has been ported to another carrier, the name returned is still the original allocation. When the metadata has nothing, `carrier` is `null` and `carrierNote` says so. We never guess a carrier.

Likewise, `lineType` comes from the numbering plan. In the US and Canada, a number can be `fixed_line_or_mobile` because the plan does not separate the two; `isMobile` is then `null` rather than a guess.

### Why use it: price and scope compared with other phone validators

Live Store prices read through the Apify API on 2026-10-29, free-plan rate, cost for a 1,000-number run including the start fee:

| Actor | Users | Per number | Start fee | Cost for 1,000 numbers |
|---|---|---|---|---|
| **This Actor** | new | $0.00088 | $0.00005 | **$0.93** |
| scrapersdelight/phone-number-validator-scraper | 45 | $0.001 | none | $1.00 |
| memo23/phone-enrichment | 415 | $0.001 | $0.005 | $1.005 |
| automation-lab/phone-number-validator | 122 | $0.00115 | $0.0115 | $1.16 |
| neuralverge/neuralverge-phone-enrichment-us | 50 | $0.10 per result | none | $100.00 |

- **Lower price at the free-plan rate in the table above.** Our price falls with your Apify plan (Bronze $0.00082, Silver $0.0007, Gold $0.00054 per number), and there is no second charge event for carrier or line type: everything is in the one price.
- **Worldwide, not one country.** The US-only enrichment Actor in the table covers US numbers; this one validates and formats numbers from every country in libphonenumber, over 240 regions.
- **Carrier, line type, location and time zones in the same row,** with an honest note when the data does not exist, instead of a blank you have to interpret.
- **Invalid numbers explain themselves.** Each failure has an `errorCode` (`TOO_SHORT`, `TOO_LONG`, `INVALID_COUNTRY_CODE`, `NOT_A_NUMBER`, `NOT_VALID_FOR_REGION`...) and a sentence in `errorReason`.
- **Reliable by construction.** No website, no proxy, no login and no third-party API sits in the path, so there is nothing to block or rate-limit. A typical 14-number run finishes in about four seconds.
- **Predictable bill.** One event per number checked, valid or not. Blank lines and duplicates are never charged, and the Actor respects your "Maximum cost per run" setting exactly.

We do not claim anything about the other Actors' output beyond their published prices; compare their sample output with ours on a handful of your own numbers.

### Input

- **Phone numbers** (required): one number per line, any common format. Plain text lines, or objects like `{"number": "07911 123456", "country": "GB"}` through the API to set a country per row.
- **Default country (ISO code)**: `US`, `GB`, `DE`, `FR`, `IN`, `BR`... used to read numbers written without `+` and the country code. Numbers that start with `+` ignore it.
- **Location language**: `en`, `de`, `fr`, `es`, `pt`, `ja`, `zh` and others, for place and carrier names. Falls back to English.
- **Max numbers**: stop after this many.

### Example input

```json
{
  "numbers": ["+14155552671", "020 7946 0958", "07911 123456", "12345", "not a number"],
  "defaultCountry": "GB",
  "language": "en",
  "maxItems": 100
}
```

### Output sample

```json
{
  "input": "020 7946 0958",
  "defaultCountry": "GB",
  "status": "valid",
  "isValid": true,
  "isPossible": true,
  "possibilityReason": "IS_POSSIBLE",
  "e164": "+442079460958",
  "international": "+44 20 7946 0958",
  "national": "020 7946 0958",
  "rfc3966": "tel:+44-20-7946-0958",
  "outOfCountry": "020 7946 0958",
  "countryCallingCode": 44,
  "regionCode": "GB",
  "countryName": "United Kingdom",
  "location": "London",
  "carrier": null,
  "carrierNote": "No carrier data for this country or number range in the offline metadata (libphonenumber carries carrier names only for some countries, mostly mobile ranges).",
  "lineType": "fixed_line",
  "isMobile": false,
  "isGeographic": true,
  "timeZones": ["Europe/London"],
  "nationalNumber": "2079460958",
  "extension": null,
  "errorCode": null,
  "errorReason": null
}
```

An invalid number keeps its verdict and reason, with the formatting fields empty:

```json
{
  "input": "12345",
  "defaultCountry": "US",
  "status": "invalid",
  "isValid": false,
  "isPossible": false,
  "possibilityReason": "TOO_SHORT",
  "e164": null,
  "errorCode": "TOO_SHORT",
  "errorReason": "Too short for this country.",
  "lineType": null
}
```

### Use cases

- **CRM and list hygiene.** Normalise every number to E.164 and drop the ones that cannot be real before an import, a campaign or a dialler upload.
- **Lead generation.** Combine with a scraper's phone column to remove malformed numbers and tag mobile versus landline.
- **Sign-up and checkout validation.** Call the Actor through the API for batches, or use the returned `errorReason` to build clear form messages.
- **SMS campaigns.** Keep only `isMobile = true` numbers and group by `regionCode` and `timeZones` to send at a sensible local hour.
- **Data migration.** Convert a mixed national and international export into one consistent format.
- **Fraud and risk screening.** Flag `voip`, `premium_rate` and `shared_cost` line types and country mismatches against the billing address.

### Tips for good results

- If your list mixes national and international numbers, set **Default country** to your home market. Numbers that start with `+` are always read as international.
- Treat `possible_but_invalid` as "right length, wrong digits": usually a mistyped area code.
- `valid` means allocated in the numbering plan. It does not mean the number is currently connected. See the scope section above.
- For a list that spans several countries without `+`, use the object form and give each row its own `country`.

### Field reference

`status` is `valid` (matches a real numbering-plan pattern), `possible_but_invalid` (plausible length only), `invalid` (wrong length) or `unparseable` (no usable number). `isPossible` is true for valid numbers as well. `possibilityReason` is libphonenumber's length verdict (`IS_POSSIBLE`, `IS_POSSIBLE_LOCAL_ONLY`, `TOO_SHORT`, `TOO_LONG`, `INVALID_LENGTH`). `location` is the geocoding description (usually a city, region or the country name). `timeZones` lists IANA zone names. `checkedAt` is the UTC time of the run.

### Pricing and cost control

Pay per number: **$0.00088 per number on the free plan, $0.00054 on the Gold plan** (Bronze $0.00082, Silver $0.0007), plus a $0.00005 start fee per run. That is $0.88 per 1,000 numbers on the free plan, with no compute surcharge for the lookups. Typical platform cost of a run is well below the price: a 296-number test used $0.0017 of compute. Blank lines and duplicates are skipped and not charged, and nothing is charged beyond the numbers delivered.

### Integrations and scheduling

Send results to Google Sheets, Slack, email, Make, Zapier or n8n with the Apify integrations, or call the Actor from your code through the REST API and the Python and JavaScript clients. Open the API tab for ready-to-copy snippets.

### Fair use and legal

All results are computed from Google's open-source libphonenumber data (Apache 2.0 licence) bundled in the Actor. No website is scraped and no personal data is looked up: the Actor only analyses the numbers you give it and returns what the numbering-plan metadata says about them. You remain responsible for having a lawful basis to process the numbers you submit (for example under GDPR) and for complying with local rules on calling and texting them. Data is accurate to the libphonenumber release shown in the run's `OUTPUT` record and numbering plans change; the engine is updated regularly.

### Use with the API, n8n, Make, Zapier or AI agents

**API** (one call, returns the rows as JSON):

```bash
curl -X POST "https://api.apify.com/v2/acts/transparent_meteorite~phone-number-validator-formatter/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+14155552671","020 7946 0958"],"defaultCountry":"GB","maxItems":100}'
```

The call waits up to 5 minutes. For bigger inputs, start the run with `/runs` instead and read the dataset when it finishes.

**Python**

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("transparent_meteorite/phone-number-validator-formatter").call(run_input={"numbers": ["+14155552671", "020 7946 0958"], "defaultCountry": "GB", "maxItems": 100})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row)
```

- **n8n, Make, Zapier:** use the Apify app's "Run Actor" step with actor `transparent_meteorite/phone-number-validator-formatter`, paste the input JSON, then map the dataset items to your sheet or CRM.
- **Clay:** add an HTTP API column that calls the run-sync endpoint above.
- **Schedules:** in Apify Console, Schedules, run it daily or weekly with the same input for a steady feed.
- **AI agents (MCP):** connect the Apify MCP server at `https://mcp.apify.com?tools=transparent_meteorite/phone-number-validator-formatter` to Claude, Cursor or any MCP client, and your agent can run libphonenumber Bulk Phone Parser on request.

### FAQ

**Does it call or text the number?** No. Nothing is dialled, texted or looked up on any network.

**Does it tell me if the number is active or reachable?** No. That needs a live HLR lookup, which this Actor does not do on purpose. It tells you whether the number is well-formed and allocated.

**Why is `carrier` empty?** The metadata has no carrier for that country or range (the US and Canada never do), or the number is a landline range. `carrierNote` states which.

**Why is `isMobile` null for a US number?** North American numbering does not separate mobile from fixed lines, so the line type is `fixed_line_or_mobile` and we do not guess.

**How do I validate numbers from several countries in one run?** Write them with `+` and the country code, or pass objects with a `country` per row.

**Are duplicates charged?** No. Identical input plus country pairs are processed once.

**Is there a limit on list size?** Up to 5,000,000 numbers per run, set by Max numbers. Use the "Maximum cost per run" option to cap spend.

**Do I need an API key or an account anywhere else?** No.

**Which formats do you accept?** Anything libphonenumber accepts: spaces, dashes, brackets, dots, leading `00` or `+`, and extensions like `x123`.

### Alternatives to other phone validators

The Store actors in the table above charged between $1.00 and $1.16 per 1,000 numbers after start fees, or $100 per 1,000 for US reverse lookup enrichment, when we read their prices on 2026-10-29. This Actor is $0.88 per 1,000 on the free plan, covers every country in libphonenumber, and states plainly what it cannot do.

### Related actors

- [Company Enrichment by Domain](https://apify.com/transparent_meteorite/company-enrichment-by-domain) to add firmographics to a lead list.
- [Decision Maker Finder](https://apify.com/transparent_meteorite/decision-maker-finder) to find the right contact at a company.
- [Website Tech Stack](https://apify.com/transparent_meteorite/website-tech-stack) for technology detection on company sites.

### Support

Found a bug or need a field? Open an issue on the Issues tab with the run URL and you will get a reply there. Feature requests are welcome.

### Changelog

- **0.1**: First private build. Offline libphonenumber validation, 26 fields, bulk input, per-row country override.

# Actor input Schema

## `numbers` (type: `array`):

One phone number per line, in any common format: +14155552671, (415) 555-2671, 020 7946 0958. Numbers without a + need a Default country below. Duplicates and blank lines are skipped and not charged.

## `defaultCountry` (type: `string`):

Two-letter ISO country code (US, GB, DE, FR, IN, BR...) used to read numbers written without a + and country code. Numbers that start with + ignore it. Leave empty if every number has a +.

## `language` (type: `string`):

Language for place and carrier names, e.g. en, de, fr, es, pt, ja, zh. Falls back to English where the metadata has no translation.

## `maxItems` (type: `integer`):

Stop after this many numbers. You are charged per number checked.

## Actor input object example

```json
{
  "numbers": [
    "+14155552671",
    "(212) 555-0147",
    "+442071838750",
    "020 7946 0958",
    "+33142685300",
    "+4930901820",
    "+81312345678",
    "+919876543210",
    "+61291234567",
    "+5511987654321",
    "+34912345678",
    "+1 800-555-0199",
    "12345",
    "not a number"
  ],
  "defaultCountry": "US",
  "language": "en",
  "maxItems": 100
}
```

# Actor output Schema

## `numbers` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "numbers": [
        "+14155552671",
        "(212) 555-0147",
        "+442071838750",
        "020 7946 0958",
        "+33142685300",
        "+4930901820",
        "+81312345678",
        "+919876543210",
        "+61291234567",
        "+5511987654321",
        "+34912345678",
        "+1 800-555-0199",
        "12345",
        "not a number"
    ],
    "defaultCountry": "US",
    "language": "en",
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("transparent_meteorite/phone-number-validator-formatter").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "numbers": [
        "+14155552671",
        "(212) 555-0147",
        "+442071838750",
        "020 7946 0958",
        "+33142685300",
        "+4930901820",
        "+81312345678",
        "+919876543210",
        "+61291234567",
        "+5511987654321",
        "+34912345678",
        "+1 800-555-0199",
        "12345",
        "not a number",
    ],
    "defaultCountry": "US",
    "language": "en",
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("transparent_meteorite/phone-number-validator-formatter").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "numbers": [
    "+14155552671",
    "(212) 555-0147",
    "+442071838750",
    "020 7946 0958",
    "+33142685300",
    "+4930901820",
    "+81312345678",
    "+919876543210",
    "+61291234567",
    "+5511987654321",
    "+34912345678",
    "+1 800-555-0199",
    "12345",
    "not a number"
  ],
  "defaultCountry": "US",
  "language": "en",
  "maxItems": 100
}' |
apify call transparent_meteorite/phone-number-validator-formatter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,transparent_meteorite/phone-number-validator-formatter"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/IHe9ObEbIgOhIAfR4/builds/qw9K6ncde8FKaR3Qf/openapi.json
