# Phone Number Validation - Normalize & Check Numbers (`benthepythondev/phone-number-validation`) Actor

Validate, normalize and enrich phone numbers: E.164, international/national format, country code, region, location, carrier, timezone and number type.

- **URL**: https://apify.com/benthepythondev/phone-number-validation.md
- **Developed by:** [Ben](https://apify.com/benthepythondev) (community)
- **Categories:** Lead generation, Business, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

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 Validation - Normalize E.164 & Check Region

Validate and normalize phone numbers in bulk. This actor turns messy phone inputs into clean, structured records with E.164 format, international and national formatting, country code, region code, location, carrier, timezone, number type and validity flags.

### What does this actor do?

Phone numbers arrive in every possible shape: local numbers, international numbers, numbers copied from websites, CRM exports, spreadsheets, forms, lead lists and scraped pages. Before you call, text, deduplicate or import those numbers into another system, you need to know whether they are parseable, possible and valid.

This actor uses Google's widely used phone-number metadata library through Python's `phonenumbers` package. It does not scrape a website, call a paid API or use a proxy. That makes it fast, deterministic and cheap to run at scale.

### Input

Provide phone numbers in `phoneNumbers`. Use international prefixes when possible, such as `+1`, `+44`, `+49` or `+33`.

If some numbers are local, set `defaultRegion` to the country they should be interpreted in. For example, use `US` for United States local numbers, `GB` for United Kingdom numbers or `DE` for German numbers.

Use `maxResults` to cap very large batches.

### Output fields

Each result can include:

- `input` - original value
- `is_possible` - whether the number length/shape is possible
- `is_valid` - whether the number is valid for its region
- `e164` - normalized international E.164 format
- `international` - human-readable international format
- `national` - national display format
- `country_code`
- `national_number`
- `region_code`
- `location`
- `carrier`
- `timezones`
- `number_type`
- `error` - parse error when the input cannot be interpreted

### Use cases

Use this actor to clean CRM exports, normalize scraped lead data, deduplicate phone numbers, validate signup form submissions, enrich business contact lists, prepare SMS campaigns, QA phone fields before importing them into HubSpot or Salesforce, or standardize numbers before joining datasets.

#### Lead list cleanup

When you scrape websites, directories or marketplaces, phone numbers often include spaces, punctuation, local formatting and mixed countries. Run the raw list through this actor first, then keep the `e164` field as your canonical phone key.

#### CRM enrichment

Import the output into a CRM to flag invalid numbers, segment leads by country, normalize display format and reduce duplicate records caused by inconsistent formatting.

Sales and operations teams often inherit contact data from multiple sources: form submissions, old spreadsheets, scraped directories, event registrations and vendor exports. The same phone number might appear as `4155552671`, `(415) 555-2671`, `+1 415 555 2671` or with country-specific spacing. Normalizing to E.164 gives you one stable value to compare, merge and sync.

#### Data pipelines

Because the actor is deterministic and does not depend on an external website, it is safe for scheduled jobs and repeatable ETL workflows. You can run it before downstream enrichment, outreach or validation steps.

For automated workflows, send the actor a list of numbers through the Apify API, then read the default dataset. A common pattern is: scrape contacts, validate phones, drop rows with parse errors, deduplicate on `e164`, then push the clean contacts into your CRM or outbound system.

#### International formatting

The `defaultRegion` setting matters when numbers do not include a country code. For example, `030 123456` could mean different things depending on the country. Setting `defaultRegion` to `DE` treats it as a German number, while `US` would not. For mixed-country datasets, include country prefixes in the raw input whenever possible.

### Notes and limits

This actor validates phone-number structure using metadata. It does not call the number, send SMS, verify live ownership or confirm that the number is currently assigned to a person or business. `is_valid` means the number is valid according to numbering-plan metadata, not that a human will answer it.

Carrier data is available for some mobile ranges and countries, but not all. Location data is usually region-level, not street-level. These limits are normal for offline phone-number validation.

The actor returns failed parses as dataset rows with `is_valid: false` and an `error` message. That makes QA easier because you can see exactly which inputs failed and why instead of silently losing rows.

### Pricing

The actor uses pay-per-result pricing. You are charged for each phone number pushed to the dataset, plus a tiny actor-start event. Failed parses are still useful rows and are charged as processed results.

### FAQ

#### Does this actor use an external paid API?

No. It runs offline using phone-number metadata packaged with the library.

#### Can it validate international numbers?

Yes. Include the country prefix or set `defaultRegion` for local numbers.

#### Does it verify if the number is active?

No. It validates format and numbering-plan metadata. It does not ping carriers or send messages.

#### Can I upload thousands of numbers?

Yes. Use the array input or API input. For very large jobs, raise `maxResults` accordingly.

#### What format should I store?

Use `e164` as the canonical machine-readable format. It is the safest field for deduplication and downstream APIs.

#### Is this useful for scraped website data?

Yes. Website phone numbers often contain labels, punctuation or inconsistent spacing. This actor helps convert those raw values into a standard format after extraction.

#### Does it detect mobile versus landline?

When metadata is available, `number_type` may identify mobile, fixed line, toll-free or other number types. Coverage varies by country.

#### Can I combine it with email validation?

Yes. A practical lead workflow is: collect company/contact data, validate emails, validate phones, deduplicate, then export only rows with at least one usable contact channel.

### You might also like

- Website Contact Extractor - find phone numbers and emails from websites
- Email Finder Verifier - enrich and validate business contacts
- Google Maps Business Scraper - collect local business leads
- BusinessesForSale Scraper - acquisition and broker leads

### Keywords

phone number validation, phone validator, E.164 formatter, phone number normalizer, validate phone numbers, CRM phone cleanup, lead list phone validation, phone carrier lookup, phone region lookup, phone number API.

# Actor input Schema

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

Phone numbers to validate and normalize. Include country codes when possible, or set a default region.
## `defaultRegion` (type: `string`):

ISO 3166-1 alpha-2 country code used for numbers without an international prefix.
## `maxResults` (type: `integer`):

Maximum phone numbers to process.

## Actor input object example

```json
{
  "phoneNumbers": [
    "+1 415 555 2671",
    "+44 20 7946 0958",
    "030 123456"
  ],
  "defaultRegion": "US",
  "maxResults": 100
}
````

# 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 415 555 2671",
        "+44 20 7946 0958",
        "030 123456"
    ],
    "defaultRegion": "US",
    "maxResults": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("benthepythondev/phone-number-validation").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 415 555 2671",
        "+44 20 7946 0958",
        "030 123456",
    ],
    "defaultRegion": "US",
    "maxResults": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("benthepythondev/phone-number-validation").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 '{
  "phoneNumbers": [
    "+1 415 555 2671",
    "+44 20 7946 0958",
    "030 123456"
  ],
  "defaultRegion": "US",
  "maxResults": 100
}' |
apify call benthepythondev/phone-number-validation --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Phone Number Validation - Normalize & Check Numbers",
        "description": "Validate, normalize and enrich phone numbers: E.164, international/national format, country code, region, location, carrier, timezone and number type.",
        "version": "1.0",
        "x-build-id": "dl8Cf9QrsuoruvneJ"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/benthepythondev~phone-number-validation/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-benthepythondev-phone-number-validation",
                "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/benthepythondev~phone-number-validation/runs": {
            "post": {
                "operationId": "runs-sync-benthepythondev-phone-number-validation",
                "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/benthepythondev~phone-number-validation/run-sync": {
            "post": {
                "operationId": "run-sync-benthepythondev-phone-number-validation",
                "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",
                "properties": {
                    "phoneNumbers": {
                        "title": "Phone numbers",
                        "type": "array",
                        "description": "Phone numbers to validate and normalize. Include country codes when possible, or set a default region.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "defaultRegion": {
                        "title": "Default region",
                        "type": "string",
                        "description": "ISO 3166-1 alpha-2 country code used for numbers without an international prefix.",
                        "default": "US"
                    },
                    "maxResults": {
                        "title": "Max results",
                        "minimum": 1,
                        "maximum": 100000,
                        "type": "integer",
                        "description": "Maximum phone numbers to process.",
                        "default": 1000
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```