# ☎️ Bulk Phone Validator (`taroyamada/phone-number-validator`) Actor

Clean and enrich scraped contact details in bulk. Convert raw phone strings into dialer-ready E.164 numbers with verified country codes and line types.

- **URL**: https://apify.com/taroyamada/phone-number-validator.md
- **Developed by:** [naoki anzai](https://apify.com/taroyamada) (community)
- **Categories:** Lead generation, Other
- **Stats:** 6 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## 📞 Phone Number Validator

Transform raw scraped phone details into perfectly structured, actionable contact data. When you extract profiles from search results or business directories, phone formats vary wildly across different pages. The Bulk Phone Validator eliminates this chaos by automatically detecting regions and standardizing strings into strict E.164 formatting.

Designed to act as the crucial enrichment layer after you run a web scraper, this tool takes your messy output and validates it offline using the industry-standard Google libphonenumber engine. It is the perfect companion for lead generation pipelines that export massive lists of websites, users, or business contacts. Instead of manually cleaning spreadsheets or paying per-ping verification APIs, you can process millions of numbers directly on the Apify platform securely and instantly.

Every run delivers rich, validated contact objects. You extract not just the cleaned phone number, but also vital metadata including the confirmed country dial code and the line classification—differentiating between mobile phones, landlines, and VoIP numbers. This is critical for sales operations teams that need to segment SMS campaigns from voice dialer lists. Schedule the validator to run alongside your email and website scrapers to guarantee your database only receives flawless, fully verified lead records.

### Lead Enrichment Pack — 3-step workflow

| Step | Actor | Job |
|------|-------|-----|
| **1** | [Contact Details Extractor](https://apify.com/taroyamada/contact-details-extractor) | Scrape public emails, phones, and social links from company pages |
| **2** | [Email Deliverability Checker](https://apify.com/taroyamada/email-deliverability-checker) | Validate emails: syntax, MX records, disposable detection, deliverability score |
| **3** | **Phone Number Validator** ← you are here | Normalize and validate phone numbers with type detection (mobile / landline / VoIP) |

### Store Quickstart

Pick the template that fits your workflow:

- **Quickstart (10 Sample Numbers)** — verify E.164 output and type detection on a mixed international set
- **Lead Validation Before Dialing** — validate a prospect phone list before loading into a dialer
- **Bulk CRM Cleanup** — normalize a CRM export with mixed formats and countries; set `defaultCountry` to your primary market
- **International Normalize** — standardize global phone data with `defaultCountry: US` fallback

### Key Features

- 📞 **250+ countries** — Every country's numbering plan supported
- 🏷️ **Type detection** — Mobile, landline, VoIP, toll-free, premium
- 📝 **Multiple format outputs** — E.164, international, national
- 🌍 **Country detection** — Auto-detect country from number format
- ⚡ **Offline processing** — google-libphonenumber runs locally, no network
- 🔑 **No API key needed** — Fully offline validation

### Use Cases

| Who | Why |
|-----|-----|
| **CRM managers** | Clean phone number columns in customer databases |
| **Sales operations** | Validate lead phone numbers before outreach |
| **SaaS onboarding** | Real-time validation at signup |
| **International compliance** | Enforce E.164 format for SMS/voice APIs |
| **Data migration** | Normalize phone numbers across systems |

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| numbers | string[] | (required) | Phone numbers to validate (max 1000) |
| defaultCountry | string | US | Default ISO country code |

#### Input Example

```json
{
  "numbers": ["+1-555-1234567", "03-1234-5678", "020 7946 0958"],
  "defaultCountry": "JP"
}
````

### Input Examples

#### Example: Single phone validation

```json
{
  "phones": [
    "+14155552671"
  ]
}
```

#### Example: Bulk with carrier rollup

```json
{
  "phones": [
    "+14155552671",
    "+819012345678",
    "+447911123456"
  ],
  "includeCarrier": true
}
```

#### Example: CSV-style hygiene check

```json
{
  "phones": [
    "415-555-2671",
    "+1 (415) 555-2671",
    "4155552671"
  ],
  "normalizeOnly": true
}
```

### Output

| Field | Type | Description |
|-------|------|-------------|
| `input` | string | Original phone string |
| `valid` | boolean | Whether the number is valid |
| `e164` | string | E.164 formatted version |
| `country` | string | ISO country code |
| `countryName` | string | Full country name |
| `carrier` | string | Carrier name (if known) |
| `lineType` | string | mobile, fixed-line, voip, etc. |
| `error` | string|null | Validation error reason |

#### Output Example

```json
{
  "input": "03-1234-5678",
  "isValid": true,
  "type": "FIXED_LINE",
  "formatted": {
    "e164": "+81312345678",
    "international": "+81 3-1234-5678",
    "national": "03-1234-5678"
  },
  "country": "Japan",
  "countryCode": "JP"
}
```

### API Usage

Run this actor programmatically using the Apify API. Replace `YOUR_API_TOKEN` with your token from [Apify Console → Settings → Integrations](https://console.apify.com/account/integrations).

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/taroyamada~phone-number-validator/run-sync-get-dataset-items?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "numbers": ["+1-555-1234567", "03-1234-5678", "020 7946 0958"], "defaultCountry": "JP" }'
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("taroyamada/phone-number-validator").call(run_input={
  "numbers": ["+1-555-1234567", "03-1234-5678", "020 7946 0958"],
  "defaultCountry": "JP"
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

#### JavaScript / Node.js

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

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });
const run = await client.actor('taroyamada/phone-number-validator').call({
  "numbers": ["+1-555-1234567", "03-1234-5678", "020 7946 0958"],
  "defaultCountry": "JP"
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Tips & Limitations

- **Set `defaultCountry` to your primary market** for numbers without a country code prefix — this dramatically improves accuracy on locally-formatted numbers.
- **Filter by `type: "mobile"`** for SMS marketing campaigns; mobile numbers are the only type reachable via SMS in most countries.
- **Use `formatted.e164`** as the canonical value for CRM import and SMS/voice API calls (Twilio, Vonage, AWS Connect).
- **Feed from Contact Details Extractor** — this validator is designed to clean the `phones` output from the extractor as Step 3 of the Lead Enrichment Pack.
- **Offline processing** — no phone numbers are ever sent to an external API. All validation runs locally using Google's libphonenumber library.
- Powered by [google-libphonenumber](https://github.com/ruimarinho/google-libphonenumber) — Google's industry-standard phone validation library.

### FAQ

**How accurate is this?**

Uses google-libphonenumber — Google's official phone validation library. Industry standard.

**Does it verify if the number is in service?**

No — format validation only. Actual reachability requires an SMS/voice ping (not offered).

**What's a 'valid' number?**

One with correct country code, valid length, and matching number plan. May still be unassigned.

**Type detection accuracy?**

Very high for countries with strict mobile/landline separation (US, JP, DE). Weaker for Asia/Africa.

**Does this charge per validation like Twilio Lookup?**

No — flat per-item dataset pricing. No per-API-call fees.

**Will it call the number to verify it's active?**

No — format and metadata validation only. No HLR lookups.

### Related Actors — Lead Enrichment Pack

This actor is **Step 3** of the Lead Enrichment Pack:

| Step | Actor | What it does |
|------|-------|-------------|
| ⬅ **Step 1** | [📧 Contact Details Extractor](https://apify.com/taroyamada/contact-details-extractor) | Scrape emails, phone numbers, and social links from company contact pages |
| ⬅ **Step 2** | [📩 Email Deliverability Checker](https://apify.com/taroyamada/email-deliverability-checker) | Syntax check, MX lookup, disposable detection, 0-100 deliverability score |

Also in the lead generation toolbox:

- [Email Deliverability Portfolio Audit API](https://apify.com/taroyamada/email-deliverability-portfolio-audit) — Audit SPF, DKIM, DMARC, MTA-STS, TLS-RPT, BIMI, and sender-readiness signals across domain portfolios with executive summaries and remediation guidance.

### Cost

**Pay Per Event**:

- `actor-start`: $0.01 (flat fee per run)
- `dataset-item`: $0.002 per output item

**Example**: 1,000 items = $0.01 + (1,000 × $0.002) = **$2.01**

No subscription required — you only pay for what you use.

### ⭐ Was this helpful?

If this actor saved you time, please [**leave a ★ rating**](https://apify.com/taroyamada/phone-number-validator/reviews) on Apify Store. It takes 10 seconds, helps other developers discover it, and keeps updates free.

Bug report or feature request? Open an issue on the [Issues tab](https://apify.com/taroyamada/phone-number-validator/issues) of this actor.

# Actor input Schema

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

Phone numbers to validate (max 1000).

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

ISO country code for numbers without country prefix.

## `delivery` (type: `string`):

Where to send results: dataset or webhook

## `webhookUrl` (type: `string`):

Webhook URL to POST results to (if delivery=webhook)

## `dryRun` (type: `boolean`):

Run without saving results (for testing)

## `maxChargeUsd` (type: `number`):

Safety cap for billable dataset rows in this run.

## Actor input object example

```json
{
  "numbers": [
    "+14155552671"
  ],
  "defaultCountry": "US",
  "delivery": "dataset",
  "dryRun": false,
  "maxChargeUsd": 1
}
```

# 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"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("taroyamada/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 = { "numbers": ["+14155552671"] }

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

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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"
  ]
}' |
apify call taroyamada/phone-number-validator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=taroyamada/phone-number-validator",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "☎️ Bulk Phone Validator",
        "description": "Clean and enrich scraped contact details in bulk. Convert raw phone strings into dialer-ready E.164 numbers with verified country codes and line types.",
        "version": "0.1",
        "x-build-id": "SfT9LPhgwYafai417"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/taroyamada~phone-number-validator/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-taroyamada-phone-number-validator",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/taroyamada~phone-number-validator/runs": {
            "post": {
                "operationId": "runs-sync-taroyamada-phone-number-validator",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/taroyamada~phone-number-validator/run-sync": {
            "post": {
                "operationId": "run-sync-taroyamada-phone-number-validator",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "numbers"
                ],
                "properties": {
                    "numbers": {
                        "title": "Phone Numbers",
                        "type": "array",
                        "description": "Phone numbers to validate (max 1000).",
                        "items": {
                            "type": "string"
                        }
                    },
                    "defaultCountry": {
                        "title": "Default Country",
                        "type": "string",
                        "description": "ISO country code for numbers without country prefix.",
                        "default": "US"
                    },
                    "delivery": {
                        "title": "Delivery",
                        "enum": [
                            "dataset",
                            "webhook"
                        ],
                        "type": "string",
                        "description": "Where to send results: dataset or webhook",
                        "default": "dataset"
                    },
                    "webhookUrl": {
                        "title": "Webhook URL",
                        "type": "string",
                        "description": "Webhook URL to POST results to (if delivery=webhook)"
                    },
                    "dryRun": {
                        "title": "Dry Run",
                        "type": "boolean",
                        "description": "Run without saving results (for testing)",
                        "default": false
                    },
                    "maxChargeUsd": {
                        "title": "Maximum charge (USD)",
                        "minimum": 0,
                        "type": "number",
                        "description": "Safety cap for billable dataset rows in this run.",
                        "default": 1
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```