# Bulk Phone Number Validator & Formatter (E.164, Offline) (`steadyline/phone-number-validator`) Actor

Validate and format phone numbers in bulk, 100% offline with Google's libphonenumber: valid or not, E.164, international, national and RFC 3966 formats, country, calling code, number type and extension. Handles messy input. $0.50 per 1,000 numbers. By Steadyline Data.

- **URL**: https://apify.com/steadyline/phone-number-validator.md
- **Developed by:** [Steadyline Data](https://apify.com/steadyline) (community)
- **Categories:** Lead generation, Developer tools, 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.50 / 1,000 number validateds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## Bulk Phone Number Validator & Formatter (E.164, Offline)

Validate and format **phone numbers in bulk**, 100% offline, with Google's **libphonenumber** (max metadata). Give it a messy CRM or lead list; get a clean row per number:

- **Valid / possible** flags (`isValid`, `isPossible`) for every country and region libphonenumber covers.
- **E.164**, **international**, **national** and **RFC 3966** (`tel:`) formats, plus country calling code, ISO country, national number, number type and extension.
- **Messy input is fine:** spaces, parentheses, dashes, leading `00` or `011`, `tel:` URIs, vanity letters (`1-800-FLOWERS`) and extensions (`ext. 12`, `x12`, `;ext=12`).
- No scraping, no live carrier lookup, no paid API. Nothing leaves the Actor.

### Use cases

- **CRM and lead-list cleanup:** normalize phones from website contact scrapes, imports and CSVs to E.164 before you dedupe or dial.
- **Lead enrichment pipelines:** run this after [Website Contact Extractor](https://apify.com/steadyline/website-contact-extractor) to validate and format every phone it found.
- **Outbound and SMS hygiene:** drop invalid numbers before you pay a dialer, WhatsApp checker or carrier lookup.
- **AI agents and MCP:** an agent can hand this Actor a list of numbers and get structured E.164 plus line type back, with no extra prompting.
- **International data entry:** national numbers from the US, UK, Germany, India and 200+ other countries, as long as you set the default country (or pass `+` / `00` international form).

### Input

```json
{
  "phoneNumbers": [
    "+1 650 253 0000",
    "(650) 253-0000",
    "+44 20 7183 8750",
    "+49 30 39405430",
    "+91 98765 43210",
    "1-800-FLOWERS",
    "+1 650 253 0000 ext. 12",
    "00442071838750",
    "not-a-number"
  ],
  "defaultCountry": "US",
  "dedupe": true
}
```

`defaultCountry` is an ISO 3166-1 alpha-2 code (`US`, `GB`, `DE`, `IN`, …). It is used only when a number is not already in international form (`+` or `00`/`011`). Numbers from several countries can be mixed in one run if they are in international form.

### Output sample

```json
{
  "input": "+1 650 253 0000 ext. 12",
  "isValid": true,
  "isPossible": true,
  "countryCallingCode": "1",
  "country": "US",
  "nationalNumber": "6502530000",
  "e164": "+16502530000",
  "international": "+1 650 253 0000 ext. 12",
  "national": "(650) 253-0000 ext. 12",
  "rfc3966": "tel:+16502530000;ext=12",
  "type": "fixed-line-or-mobile",
  "extension": "12",
  "error": null,
  "charged": true
}
```

The dataset has two views: **Overview** and **Formats**.

`type` is one of: `mobile`, `fixed-line`, `fixed-line-or-mobile`, `voip`, `toll-free`, `premium-rate`, `shared-cost`, `personal-number`, `pager`, `uan`, `voicemail`, or `null` when unknown.

`error` is set when `isValid` is false: `empty`, `not-a-number`, `missing-country`, `too-short`, `too-long`, `invalid-country`, or `invalid` (possible length but not a valid number, e.g. a reserved range).

### Pricing (pay per event)

| Event | Price | When |
|---|---|---|
| `number-validated` | **$0.0005** per number | A unique phone number was analyzed, whether it is valid or not. |
| `apify-actor-start` | $0.00005 per GB-run (min 1) | The Actor starts. Default memory is 256 MB, so this is usually one event. |

Empty inputs and duplicates are **never charged**. When **Skip duplicates** is on (the default), later copies are dropped. When it is off, later copies still appear in the dataset with `charged: false` and `duplicate: true`.

**Cost example:** 10,000 unique numbers costs **$5.00** in events, plus a fraction of a cent to start the run.

### Use it from AI agents (MCP), Zapier, Make, n8n or the API

**AI agents (Claude, Cursor, VS Code, ChatGPT and other MCP clients).** Add Apify's hosted MCP server with just this Actor as a tool:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=steadyline/phone-number-validator"
    }
  }
}
```

Sign in with Apify (OAuth) on first connect, or add an `Authorization: Bearer <APIFY_TOKEN>` header. Then ask your agent, for example:

> Use steadyline/phone-number-validator to validate and format this list of phone numbers to E.164, drop invalid ones, and keep extensions.

The agent sees this Actor's input schema and output fields, so it can call it without extra prompting. Agents that use the general Apify MCP server can also find it with `search-actors`.

This Actor uses pay-per-event pricing with limited permissions, so it can also be run through Apify's agentic payments (no Apify account needed for the agent). See the [Apify docs](https://docs.apify.com/platform/integrations/mcp#agentic-payments).

**Zapier, Make and n8n.** Use the official Apify app: Zapier "Run Actor" action, Make "Run an Actor" module, or the n8n Apify node. Choose `steadyline/phone-number-validator`, paste the input below, then use "Get dataset items" (or the run's dataset) to send results to Google Sheets, Slack, a CRM or a database.

**API (any language).** Run it and get the results in one call:

```bash
curl -X POST "https://api.apify.com/v2/acts/steadyline~phone-number-validator/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumbers":["+1 650 253 0000","(650) 253-0000","+44 20 7183 8750","+49 30 39405430","+91 98765 43210","1-800-FLOWERS","+1 650 253 0000 ext. 12","not-a-number"],"defaultCountry":"US"}'
```

Or with the Python client (`pip install apify-client`):

```python
from apify_client import ApifyClient
client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("steadyline/phone-number-validator").call(run_input={"phoneNumbers": ["+1 650 253 0000", "(650) 253-0000", "+44 20 7183 8750", "+49 30 39405430", "+91 98765 43210", "1-800-FLOWERS", "+1 650 253 0000 ext. 12", "not-a-number"], "defaultCountry": "US"})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

### Works well with other Steadyline Data tools

- **Contact then clean:** [Website Contact Extractor](https://apify.com/steadyline/website-contact-extractor) finds public phones and emails on company sites; this Actor formats the phones to E.164; [Bulk Email Validator](https://apify.com/steadyline/email-deliverability-checker) cleans the emails (MX, disposable, typo check, no SMTP).
- **Lead list QA:** after a scrape or import, run this Actor on the phone column and the email validator on the email column in parallel.
- Related: [Website Contact Scraper](https://apify.com/steadyline/website-contact-extractor), [Bulk Email Validator: MX, Disposable & Typo Check (No SMTP)](https://apify.com/steadyline/email-deliverability-checker), [Company Team Page Scraper](https://apify.com/steadyline/website-team-extractor).

### FAQ

**Does this tell me if a number is in service, or who owns it?**
No. It is an offline format and validity check, not a live carrier, HLR, TCPA or reverse-lookup API. `isValid` means the number is a real number *plan* for that country (right length and prefix), not that it is currently assigned or reachable.

**Which library does it use?**
[libphonenumber-js](https://www.npmjs.com/package/libphonenumber-js) with the **max** metadata build, a JavaScript port of Google's libphonenumber. Geocoding, carrier name and timezone metadata are not included (those data files are large); you get validation, type and formatting only.

**Do I need a default country?**
Only for national numbers such as `(650) 253-0000` or `020 7183 8750`. International numbers starting with `+`, `00` or `011` are parsed without it. If a national number is given with no default country, the row comes back as `missing-country` and is still charged (it was analyzed).

**How are extensions and vanity numbers handled?**
Extensions in `ext.`, `extension`, `x`, `#` and `;ext=` forms are returned in `extension` and in the RFC 3966 URI. Letter-based vanity numbers such as `1-800-FLOWERS` are converted with the standard keypad mapping, then validated.

**Which numbers are charged?**
Each unique number analyzed is $0.0005, including invalid ones (knowing a number is invalid is the point). Empty rows and duplicates are free (`charged: false`).

**Can I run it on a schedule?** Yes. Create an Apify Schedule (or a saved Task with a schedule) and connect a webhook or integration to receive results.

**Need a feature or found a bug?** Open an issue on the Issues tab of this page or email steadylinedata@proton.me. Built and maintained by **Steadyline Data**.

### Acceptable use

Use this Actor only on numbers you are legally allowed to process: for example your own customers, sign-ups or CRM contacts, under a legitimate interest or consent. It does not look up owners or scrape directories. Don't use it to build or validate lists for unsolicited calls or SMS. You're responsible for complying with GDPR, TCPA, ICO, CASL and similar laws.

***

Built and maintained by **Steadyline Data**. Validation uses libphonenumber-js (MIT), a port of Google's libphonenumber.

# Actor input Schema

## `phoneNumbers` (type: `array`):

Phone numbers in any common form: E.164, national, with spaces or parentheses, leading 00/011, tel: URIs, vanity letters (1-800-FLOWERS) and extensions (ext. 12, x12). National numbers need Default country.

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

ISO 3166-1 alpha-2 country code (US, GB, DE, IN, …) used when a number is not in international format. Ignored for numbers that already start with + or 00.

## `dedupe` (type: `boolean`):

Drop later copies of the same number (same E.164 and extension, or the same digits when the number is invalid). Duplicates are never charged. Turn off to keep every row; later copies are still free.

## Actor input object example

```json
{
  "phoneNumbers": [
    "+1 650 253 0000",
    "(650) 253-0000",
    "+44 20 7183 8750",
    "+49 30 39405430",
    "+91 98765 43210",
    "1-800-FLOWERS",
    "+1 650 253 0000 ext. 12",
    "00442071838750",
    "not-a-number"
  ],
  "defaultCountry": "US",
  "dedupe": true
}
```

# Actor output Schema

## `overview` (type: `string`):

Validity, country, type and E.164 per number.

## `formats` (type: `string`):

E.164, international, national and RFC 3966 formats.

# 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 = {
    "phoneNumbers": [
        "+1 650 253 0000",
        "(650) 253-0000",
        "+44 20 7183 8750",
        "+49 30 39405430",
        "+91 98765 43210",
        "1-800-FLOWERS",
        "+1 650 253 0000 ext. 12",
        "00442071838750",
        "not-a-number"
    ],
    "defaultCountry": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("steadyline/phone-number-validator").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 = {
    "phoneNumbers": [
        "+1 650 253 0000",
        "(650) 253-0000",
        "+44 20 7183 8750",
        "+49 30 39405430",
        "+91 98765 43210",
        "1-800-FLOWERS",
        "+1 650 253 0000 ext. 12",
        "00442071838750",
        "not-a-number",
    ],
    "defaultCountry": "US",
}

# Run the Actor and wait for it to finish
run = client.actor("steadyline/phone-number-validator").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 '{
  "phoneNumbers": [
    "+1 650 253 0000",
    "(650) 253-0000",
    "+44 20 7183 8750",
    "+49 30 39405430",
    "+91 98765 43210",
    "1-800-FLOWERS",
    "+1 650 253 0000 ext. 12",
    "00442071838750",
    "not-a-number"
  ],
  "defaultCountry": "US"
}' |
apify call steadyline/phone-number-validator --silent --output-dataset

```

## MCP server setup

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

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/RVf3byPbZ4ACvq8WN/builds/J8ve8Fh1kQhpxzGEY/openapi.json
