# Phone Number Validator API - E.164, Line Type & Risk Flags (`george.the.developer/phone-number-validator`) Actor
Validate and normalize phone numbers. Returns E.164, national/international format, country, calling code, line type, tel URI, and risk flags. Invalid rows are free.
- **URL**: https://apify.com/george.the.developer/phone-number-validator.md
- **Developed by:** [George Kioko](https://apify.com/george.the.developer) (community)
- **Categories:** Developer tools, Lead generation
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
Pay per usage
This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage
## 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 API - E.164, Line Type & Risk Flags
Validate and normalize phone numbers at scale. Give it a single number or a list of up to 100, and get back clean E.164, the country, the international and national formats, the line type, a `tel:` URI, and deterministic risk flags. Invalid and unparsable rows are returned for free; only valid keepers are billed.
Validation is fully offline and deterministic, backed by Google's libphonenumber metadata through [`libphonenumber-js`](https://www.npmjs.com/package/libphonenumber-js). No accounts, no keys, no scraping.
### How it works
```mermaid
flowchart LR
A[Standby API call
or batch input] --> B[Normalize input
strip spaces, parse with
defaultCountry hint]
B --> C[Validate with
libphonenumber-js]
C --> D{Valid?}
D -- no --> E[Return row
valid=false + reason
FREE, not charged]
D -- yes --> F[Derive E.164, formats,
country, line type,
risk flags]
F --> G[Actor.charge
phone-number-validated]
E --> H[Dataset row
or JSON response]
G --> H
````
```mermaid
sequenceDiagram
participant Client
participant Standby as Standby URL
participant Actor
participant Lib as libphonenumber-js
Client->>Standby: GET /lookup?phoneNumber=...
Standby->>Actor: route request
Actor->>Lib: parse + validate
Lib-->>Actor: valid / line type / formats
alt number is valid
Actor->>Actor: Actor.charge("phone-number-validated")
else invalid or unparsable
Note over Actor: no charge (free)
end
Actor-->>Client: JSON result
```
### What it does
- Normalizes any input to **E.164** (`+12133734253`) when the number is valid
- Returns **national** and **international** display formats
- Detects **country** (ISO 3166 alpha-2) and **country calling code**
- Reports **line type** when the metadata supports it (`MOBILE`, `FIXED_LINE`, `TOLL_FREE`, `PREMIUM_RATE`, `VOIP`, ...)
- Emits a `tel:` **URI** for click-to-call
- Adds deterministic **risk flags** inferred from validity, possibility, and line type
- Cleans bulk lead lists: invalid and unparsable rows are returned for free
### What it does NOT do (yet)
This is honest about its scope. v1 is a validation and normalization API. It does **not**:
- Perform paid HLR / network carrier lookups
- Scrape Truecaller or any consumer caller-ID app
- Return the real carrier name or the number's timezone
For that reason `carrier` and `timezone` are always returned as `null`, each with an explicit status field (`carrierLookupStatus: "not_configured"`, `timezoneLookupStatus: "not_available_offline"`). The output shape is stable, so a future optional paid-provider integration can fill those fields without breaking your code. We will not fake carrier data.
### Modes
#### 1. Standby API (real-time)
Leave the input empty and call the Actor as an HTTP service.
| Method | Path | Description |
| ------ | ---- | ----------- |
| GET | `/` or `/health` | Service metadata and endpoint list |
| GET | `/lookup?phoneNumber=...&defaultCountry=US` | Validate one number |
| POST | `/lookup` | Validate one number (JSON body) |
| POST | `/lookup-batch` | Validate up to 100 numbers (JSON body) |
CORS is enabled and every response is JSON. `400` for bad or missing input, `404` for unknown routes, `500` for unexpected errors.
**Example: GET single lookup**
```bash
curl "https:///lookup?phoneNumber=%2B447400123456"
```
**Example: POST single lookup**
```bash
curl -X POST https:///lookup \
-H "Content-Type: application/json" \
-d '{"phoneNumber":"(213) 373-4253","defaultCountry":"US","includeRiskSignals":true}'
```
**Example: POST batch (max 100)**
```bash
curl -X POST https:///lookup-batch \
-H "Content-Type: application/json" \
-d '{"phoneNumbers":["+12133734253","07400 123456","not a phone"],"defaultCountry":"GB"}'
```
#### 2. Batch Actor
Run it with input. Provide either a single `phoneNumber` or a `phoneNumbers` array (up to 100). One dataset row is pushed per number, in input order. Export as JSON, CSV, or Excel from the dataset.
```json
{
"phoneNumbers": ["+12133734253", "07400 123456", "not a phone number"],
"defaultCountry": "GB",
"includeRiskSignals": true
}
```
### Input
| Field | Type | Default | Description |
| ----- | ---- | ------- | ----------- |
| `phoneNumber` | string | `+12133734253` | Single number. E.164 or national format with a `defaultCountry` hint. |
| `phoneNumbers` | string\[] | none | Bulk list, max 100. Takes precedence over `phoneNumber`. |
| `defaultCountry` | string | `US` | ISO 3166-1 alpha-2 code used to parse national-format numbers. Ignored for `+E.164` input. |
| `includeRiskSignals` | boolean | `true` | Attach risk flags to each result. |
### Output
One object per number:
```json
{
"input": "07400 123456",
"valid": true,
"isPossible": true,
"e164": "+447400123456",
"nationalFormat": "07400 123456",
"internationalFormat": "+44 7400 123456",
"uri": "tel:+447400123456",
"countryCode": "GB",
"countryCallingCode": "44",
"lineType": "MOBILE",
"carrier": null,
"carrierLookupStatus": "not_configured",
"timezone": null,
"timezoneLookupStatus": "not_available_offline",
"riskFlags": [],
"riskScore": 0,
"confidence": "high",
"reason": "Valid phone number",
"error": null
}
```
#### Risk flags
Risk flags are derived only from validation facts, so they are reproducible:
| Flag | Meaning |
| ---- | ------- |
| `invalid` | The number is not valid for any region. |
| `not_possible` | The length or pattern can't be a real number. |
| `possible_not_valid` | Right length, but not a valid number for any region. |
| `unparsable` | Could not be parsed at all (empty or non-numeric). |
| `premium_rate` | Premium-rate line type (`PREMIUM_RATE`). |
| `voip` | VoIP line type. |
| `pager` | Pager line type. |
| `shared_cost` | Shared-cost line type. |
`confidence` is `high` for valid numbers, `medium` for possible-but-invalid, and `low` for not-possible or unparsable.
### Pricing
Pay per event:
- **Current Apify scheduled price: `phone-number-validated` - $0.003** per **valid** number returned.
- **Recommended next price after Apify's pricing cooldown: $0.004** per **valid** number returned.
Only valid numbers are billed. Invalid, unparsable, and possible-but-invalid rows are returned for free, so cleaning a noisy lead list never costs more than the keepers it produces.
Apify currently blocks another pricing modification until **2026-07-16** because this Actor's first pricing record was just created. The table below shows the recommended next price once the cooldown allows it.
| Valid numbers | Cost at $0.004 |
| ------------- | ---- |
| 100 | $0.40 |
| 1,000 | $4.00 |
| 10,000 | $40.00 |
A batch of 100 with 80 valid numbers costs $0.32 (the 20 bad rows are free).
#### Competitor price positioning
Surveyed against the live Apify Store on 2026-06-17. The honest comparison set is split into two groups: cheap offline libphonenumber validators and higher-priced phone-intelligence APIs that add HLR, carrier, owner, fraud, or messaging signals. This Actor is a clean validation/normalization API, so the target price stays below the intelligence tier and below EasyAPI while charging only for valid rows.
| Actor | Per-number price | What you get |
| ----- | ---------------- | ------------ |
| [khadinakbar/phone-number-lookup-api](https://apify.com/khadinakbar/phone-number-lookup-api) | $0.025 | Phone intelligence: HLR carrier, owner/CNAM, fraud score, breach data, WhatsApp/Telegram |
| [easyapi/phone-number-validation](https://apify.com/easyapi/phone-number-validation) | ~$0.00499 ($4.99 per 1,000) | Validation, parse, type, location, formats |
| **[george.the.developer/phone-number-validator](https://apify.com/george.the.developer/phone-number-validator)** | **current $0.003; target $0.004 valid only** | **E.164, formats, country, line type, deterministic risk flags. Invalid rows free.** |
| [zhorex/phone-number-validator](https://apify.com/zhorex/phone-number-validator) | ~$0.002 ($2.00 per 1,000) | Offline libphonenumber validation, timezone/location, carrier where metadata supports it |
| [junipr/phone-number-validator](https://apify.com/junipr/phone-number-validator) | ~$0.0013 ($1.30 per 1,000) | Validation, formats, line type, region, carrier/location claims |
Why $0.004, not $0.0075:
- $0.0075 would be too high for v1 because this Actor does not return live HLR, real carrier, owner, fraud, SIM, WhatsApp, or Telegram data.
- $0.004 is still a **33% lift** over the current $0.003 price while staying below EasyAPI and far below phone-intelligence APIs.
- On a noisy list with 65% valid numbers, $0.004 per valid result works out to about **$2.60 per 1,000 input rows** because the invalid 35% is free.
- The premium over cheaper offline peers is justified by valid-only billing, a real-time Standby API, batch mode, and deterministic risk flags.
Why pay more than the cheapest offline validator:
- You pay only for valid rows, not every input row.
- You can call it as a real-time HTTP Standby API or as a batch Actor.
- The output is honest: no fake carrier, timezone, HLR, or owner data.
- Risk flags are deterministic and reproducible for lead-list cleaning.
```mermaid
flowchart LR
subgraph INTEL["Intelligence tier: $0.015 to $0.025"]
A1[HLR carrier / owner
fraud / messaging signals]
end
subgraph OURS["This actor: target $0.004"]
B1[Offline validation
valid-only billing
Standby API + risk flags]
end
subgraph OFFLINE["Offline peers: $0.0013 to $0.002"]
C1[Per-result validation
usually all rows billed]
end
A1 -. richer data, higher price .-> B1
B1 -. pay only for keepers .-> C1
```
### Notes on line type and country
`lineType` comes from the bundled metadata and may be `null` for some countries even when the number is valid. Country detection can also be `null` for numbers that are possible but not assigned to a specific region. Both are reported honestly rather than guessed.
### Limitations
- No real carrier name or timezone in v1 (see "What it does NOT do").
- Line type availability varies by country.
- Validation reflects numbering-plan rules, not whether a number is currently active on a network. That requires a paid HLR lookup, which is out of scope for v1.
# Actor input Schema
## `phoneNumber` (type: `string`):
Single phone number to validate. Accepts E.164 (+12133734253) or national format with a defaultCountry hint.
## `phoneNumbers` (type: `array`):
Array of phone numbers for bulk validation (max 100).
## `defaultCountry` (type: `string`):
ISO 3166-1 alpha-2 country code (e.g. US, GB, DE) used to parse numbers given in national format. Ignored for numbers already in +E.164 form.
## `includeRiskSignals` (type: `boolean`):
Add deterministic risk flags (invalid, not\_possible, possible\_not\_valid, premium\_rate, voip, etc.) to each result.
## Actor input object example
```json
{
"phoneNumber": "+12133734253",
"defaultCountry": "US",
"includeRiskSignals": true
}
```
# 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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {};
// Run the Actor and wait for it to finish
const run = await client.actor("george.the.developer/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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {}
# Run the Actor and wait for it to finish
run = client.actor("george.the.developer/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 '{}' |
apify call george.the.developer/phone-number-validator --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=george.the.developer/phone-number-validator",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Phone Number Validator API - E.164, Line Type & Risk Flags",
"description": "Validate and normalize phone numbers. Returns E.164, national/international format, country, calling code, line type, tel URI, and risk flags. Invalid rows are free.",
"version": "1.0",
"x-build-id": "Yqkb1OsUgcXz9oXXG"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/george.the.developer~phone-number-validator/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-george.the.developer-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/george.the.developer~phone-number-validator/runs": {
"post": {
"operationId": "runs-sync-george.the.developer-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/george.the.developer~phone-number-validator/run-sync": {
"post": {
"operationId": "run-sync-george.the.developer-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",
"properties": {
"phoneNumber": {
"title": "Phone Number",
"type": "string",
"description": "Single phone number to validate. Accepts E.164 (+12133734253) or national format with a defaultCountry hint.",
"default": "+12133734253"
},
"phoneNumbers": {
"title": "Phone Numbers (Bulk)",
"maxItems": 100,
"type": "array",
"description": "Array of phone numbers for bulk validation (max 100).",
"items": {
"type": "string"
}
},
"defaultCountry": {
"title": "Default Country",
"type": "string",
"description": "ISO 3166-1 alpha-2 country code (e.g. US, GB, DE) used to parse numbers given in national format. Ignored for numbers already in +E.164 form.",
"default": "US"
},
"includeRiskSignals": {
"title": "Include Risk Signals",
"type": "boolean",
"description": "Add deterministic risk flags (invalid, not_possible, possible_not_valid, premium_rate, voip, etc.) to each result.",
"default": true
}
}
},
"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
}
}
}
}
}
}
}
}
}
}
```