# Phone Number Validation API (`maximedupre/phone-number-validation`) Actor

Check phone numbers against their numbering plan and format valid numbers. Get E.164, national, and international forms, plus country, line type, location, and likely time zones.

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

## Pricing

from $0.01 / 1,000 phone numbers

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/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/docs.md):

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

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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

### 📞 Check and format phone numbers

This phone number validator helps developers, data teams, and sales teams clean phone lists. It checks numbering-plan rules and returns E.164, national, and international formats, plus country, line type, location, and likely time zones when known.

- **[Phone Number Validator](https://apify.com/maximedupre/phone-number-validation/examples/phone-number-validator)** — check whether numbers fit their numbering plan.
- **[International Phone Number Validation](https://apify.com/maximedupre/phone-number-validation/examples/international-phone-number-validation)** — use a country code for local numbers and check numbers from many regions.
- **[E.164 Phone Number Validation](https://apify.com/maximedupre/phone-number-validation/examples/e-164-phone-number-validation)** — turn valid numbers into a standard E.164 form.
- **[Phone Number Formatting](https://apify.com/maximedupre/phone-number-validation/examples/phone-number-formatting)** — get national and international display forms.
- **[Phone Number Type Checker](https://apify.com/maximedupre/phone-number-validation/examples/phone-number-type-checker)** — label mobile, fixed-line, VoIP, toll-free, and other known number types.
- **[Extract Phone Numbers from Text](https://apify.com/maximedupre/phone-number-validation/examples/extract-phone-numbers-from-text)** — find phone-like values in text and check them with your list.

#### 📦 Returned data

Each saved dataset row is one valid phone number. It includes the first input source where that number was found. If the same normalized number appears again, the later match is not saved.

Returned fields include:

- `phoneNumber` and `source`
- `e164`, `internationalFormat`, and `nationalFormat`
- `isValid` and `isPossible`
- `countryCode` and `callingCode`
- `type`, `extension`, `location`, and `timeZones`

Location, country, and time-zone data may be empty when numbering-plan data does not provide it. These checks do not show whether a number is active, assigned, or owned by a person. They do not check WhatsApp accounts.

#### ▶️ Running the Actor

1. Add one or more values to **Phone numbers**.
2. Set **Default country** for numbers that have no country calling code.
3. You may add **Text to scan** and turn on **Keep rejected inputs**.
4. Run the Actor and open the dataset.

#### 🧾 Input

```json
{
  "phoneNumbers": [
    "+1 202-555-0123",
    "020 7946 0958"
  ],
  "defaultCountry": "GB",
  "text": "Call the Paris office at +33 1 42 68 53 00.",
  "includeInvalid": true
}
````

- `phoneNumbers` is the required list to check.
- `defaultCountry` is an optional two-letter country code used for national numbers.
- `text` is optional free-form text. Phone-like values found there are checked too.
- `includeInvalid` keeps rejected values and their reason in the `REJECTED_INPUTS` file. It is `true` by default.

#### 📊 Output

A dataset row can look like this:

```json
{
  "phoneNumber": "+1 202-555-0123",
  "source": "phoneNumbers",
  "e164": "+12025550123",
  "internationalFormat": "+1 202-555-0123",
  "nationalFormat": "(202) 555-0123",
  "isValid": true,
  "isPossible": true,
  "countryCode": "US",
  "callingCode": "1",
  "type": "fixedLineOrMobile",
  "timeZones": ["America/New_York"]
}
```

When **Keep rejected inputs** is on, unparseable or implausible values go to `REJECTED_INPUTS` with `phoneNumber`, `reason`, and `source`. They do not create valid-number dataset rows.

#### 💳 Pricing

This Actor uses pay-per-event pricing. You pay for each valid phone number saved to the dataset. Rejected inputs, repeated later matches, and runs with no valid saved phone number are not charged as phone-number events. Apify platform costs may still apply.

#### 🔌 Integrations

https://www.youtube.com/watch?v=bNACk1\_S\_6w\&list=PLObrtcm1Kw6MUrlLNDbK9QRg8VDJg0gOW\&index=4

Export the dataset as JSON, CSV, Excel, XML, RSS, or HTML. You can also run the Actor with the Apify API, schedule runs, or send finished data to webhooks and other Apify integrations.

#### ❓ FAQ

**Does this verify that a phone number is active or belongs to someone?**\
No. It checks the number against numbering-plan data. It does not call, text, run an HLR lookup, or check a subscriber.

**Can it check national numbers without a `+` prefix?**\
Yes. Set `defaultCountry` to the two-letter country code that gives those numbers their local context.

**What happens when the same number uses two formats?**\
The Actor uses the normalized number to spot repeats. It saves the first valid match and ignores later matches for that number.

**Is a regex enough for E.164 validation?**\
A regex can check the shape of a value. This Actor also parses the number and checks its length and pattern against numbering-plan data.

**Why can a valid number still be unused?**\
A valid result means the number fits its numbering plan. It does not prove that a carrier assigned it or that a person can answer it.

**Do I need a phone service API key?**\
No third-party phone service key is needed for these numbering-plan checks. You still run the Actor through Apify.

### 📝 Changelog

- 0.1.0: Initial release.

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~phone-number-validation/issues) and I'll fix or implement it in less than 24h 🫡

### 🔗 Related Actors

- [Google Maps Phone Number Scraper](https://apify.com/maximedupre/google-maps-phone-number-scraper) — collect public business phone numbers from Google Maps before checking their format.
- [SMTP Email Verifier](https://apify.com/maximedupre/smtp-email-verifier) — check email syntax, MX records, and SMTP evidence while cleaning contact lists.
- [Website Emails Scraper](https://apify.com/maximedupre/website-emails-scraper) — find public email addresses on a known list of sites.
- [Person Email Finder — Name + Company to Email API](https://apify.com/maximedupre/business-email-finder) — infer likely work email addresses from a name and company site.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

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

Add the phone numbers to check. Use a country calling code, such as +1, or set a default country below.

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

Enter a two-letter country code, such as US or GB. This country is used for numbers that do not start with a country calling code.

## `text` (type: `string`):

Enter free-form text to find and check phone-like values. The Actor checks them with the phone number list.

## `includeInvalid` (type: `boolean`):

Keep inputs that cannot be parsed or are not plausible. Each rejected input includes a clear reason.

## `__isDebug` (type: `boolean`):

Turns on safe debug logs and resource telemetry.

## Actor input object example

```json
{
  "phoneNumbers": [
    "+1 202-456-1111",
    "020 7946 0958 ext 123",
    "not a phone"
  ],
  "defaultCountry": "US",
  "text": "Call us at +1 202-555-0123.",
  "includeInvalid": true
}
```

# Actor output Schema

## `phoneNumbers` (type: `string`):

Valid phone numbers with standard formats and useful details.

## `rejectedInputs` (type: `string`):

Inputs that could not be checked, with a clear reason. This file is made only when rejected inputs are kept.

# 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 202-456-1111",
        "020 7946 0958 ext 123",
        "not a phone"
    ],
    "defaultCountry": "GB",
    "text": "For US assistance call (202) 456-1111; for Paris call +33 1 42 68 53 00."
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/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 202-456-1111",
        "020 7946 0958 ext 123",
        "not a phone",
    ],
    "defaultCountry": "GB",
    "text": "For US assistance call (202) 456-1111; for Paris call +33 1 42 68 53 00.",
}

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/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 202-456-1111",
    "020 7946 0958 ext 123",
    "not a phone"
  ],
  "defaultCountry": "GB",
  "text": "For US assistance call (202) 456-1111; for Paris call +33 1 42 68 53 00."
}' |
apify call maximedupre/phone-number-validation --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Phone Number Validation API",
        "description": "Check phone numbers against their numbering plan and format valid numbers. Get E.164, national, and international forms, plus country, line type, location, and likely time zones.",
        "version": "0.1",
        "x-build-id": "dTw24fbM8VLI4a92a"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/maximedupre~phone-number-validation/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-maximedupre-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/maximedupre~phone-number-validation/runs": {
            "post": {
                "operationId": "runs-sync-maximedupre-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/maximedupre~phone-number-validation/run-sync": {
            "post": {
                "operationId": "run-sync-maximedupre-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",
                "required": [
                    "phoneNumbers"
                ],
                "properties": {
                    "phoneNumbers": {
                        "title": "Phone numbers",
                        "minItems": 1,
                        "maxItems": 100000,
                        "type": "array",
                        "description": "Add the phone numbers to check. Use a country calling code, such as +1, or set a default country below.",
                        "items": {
                            "type": "string",
                            "minLength": 1
                        },
                        "default": [
                            "+1 202-456-1111",
                            "020 7946 0958 ext 123",
                            "not a phone"
                        ]
                    },
                    "defaultCountry": {
                        "title": "Default country",
                        "pattern": "^[A-Za-z]{2}$",
                        "minLength": 2,
                        "maxLength": 2,
                        "type": "string",
                        "description": "Enter a two-letter country code, such as US or GB. This country is used for numbers that do not start with a country calling code.",
                        "default": "GB"
                    },
                    "text": {
                        "title": "Text to scan",
                        "type": "string",
                        "description": "Enter free-form text to find and check phone-like values. The Actor checks them with the phone number list.",
                        "default": "For US assistance call (202) 456-1111; for Paris call +33 1 42 68 53 00."
                    },
                    "includeInvalid": {
                        "title": "Keep rejected inputs",
                        "type": "boolean",
                        "description": "Keep inputs that cannot be parsed or are not plausible. Each rejected input includes a clear reason.",
                        "default": true
                    },
                    "__isDebug": {
                        "title": "Debug mode",
                        "type": "boolean",
                        "description": "Turns on safe debug logs and resource telemetry."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```