# Phone Number Validator (`zenapi/phone-number-validator`) Actor A powerful Apify Actor for validating and parsing phone numbers from any country. Get instant validation results with detailed information including formatting options, number type classification, and metadata for phone numbers worldwide. - **URL**: https://apify.com/zenapi/phone-number-validator.md - **Developed by:** [Zen API](https://apify.com/zenapi) (community) - **Categories:** Developer tools - **Stats:** 79 total users, 4 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing $2.00/month + usage To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors ## 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 - Apify Actor A powerful Apify Actor for validating and parsing phone numbers from any country. Get instant validation results with detailed information including formatting options, number type classification, and metadata for phone numbers worldwide. ### Features - **Global Coverage**: Validate phone numbers from all countries/regions worldwide - **Multiple Formats**: Output numbers in International, National, E164, and RFC3966 formats - **Number Type Detection**: Identify Mobile, Fixed Line, Toll-Free, Premium Rate, VoIP, and more - **Detailed Validation**: Get specific error messages for invalid numbers - **Flexible Input**: Accept numbers with or without country codes - **Extension Support**: Parse and preserve phone number extensions - **High Accuracy**: Industry-standard validation algorithms ### Input Schema ```json { "phoneNumbers": ["+1 650-253-0000", "+44 20 7183 8750"], "defaultRegion": "US" } ```` #### Input Parameters | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ----------------------------------------------- | | `phoneNumbers` | Array | Yes | Array of phone numbers to validate (supports single or multiple) | | `defaultRegion` | String | No | ISO 3166-1 alpha-2 country code (default: "US") | ### Output #### Single Number Validation When validating a single phone number: ```json { "type": "single_validation", "input": "+1 650-253-0000", "success": true, "isValid": true, "isPossible": true, "countryCode": 1, "nationalNumber": "6502530000", "region": "US", "formatted": { "international": "+1 650-253-0000", "national": "(650) 253-0000", "e164": "+16502530000", "rfc3966": "tel:+1-650-253-0000" }, "type": "FIXED_LINE_OR_MOBILE", "metadata": { "isValidForRegion": true, "canBeInternationallyDialled": true } } ``` #### Output Attributes for Successful Validation | Attribute | Type | Description | |-----------|------|-------------| | `type` | String | Indicates validation type (`single_validation` or `batch_validation`) | | `input` | String | The original phone number input provided | | `success` | Boolean | Whether the parsing operation succeeded (not same as validation) | | `isValid` | Boolean | Whether the phone number is valid according to the region's rules | | `isPossible` | Boolean | Whether the phone number is possible based on length | | `countryCode` | Number | The country calling code (e.g., 1 for US, 44 for UK) | | `nationalNumber` | String | The national significant number without country code | | `region` | String | ISO 3166-1 alpha-2 country code of the number | | `extension` | String/null | Phone extension if present (e.g., "123" from "+1 650 253 0000 ext 123") | | `formatted` | Object | Contains the number in various formats | | `formatted.international` | String | International format (e.g., "+1 650-253-0000") | | `formatted.national` | String | National format (e.g., "(650) 253-0000") | | `formatted.e164` | String | E164 format (e.g., "+16502530000") | | `formatted.rfc3966` | String | RFC 3966 format (e.g., "tel:+1-650-253-0000") | | `type` | String | Number type classification (see Number Types section) | | `metadata` | Object | Additional metadata about the number | | `metadata.isValidForRegion` | Boolean | Whether the number is valid for its detected region | | `metadata.canBeInternationallyDialled` | Boolean | Whether the number can be dialled internationally | #### Invalid Number ```json { "type": "single_validation", "input": "123", "success": true, "isValid": false, "isPossible": false, "validationError": "TOO_SHORT", "errorMessage": "The phone number is too short for the region" } ``` #### Batch Validation Result ```json { "type": "batch_validation", "totalProcessed": 4, "summary": { "total": 4, "valid": 3, "possible": 3, "invalid": 1 }, "results": [ // Individual validation results for each number ] } ``` ### Number Types The Actor identifies the following phone number types: | Type | Description | | ---------------------- | ---------------------------------- | | `FIXED_LINE` | Landline numbers | | `MOBILE` | Mobile/cellular numbers | | `FIXED_LINE_OR_MOBILE` | Could be either type | | `TOLL_FREE` | Toll-free numbers (800, 888, etc.) | | `PREMIUM_RATE` | Premium rate numbers | | `SHARED_COST` | Shared cost numbers | | `VOIP` | Voice over IP numbers | | `PERSONAL_NUMBER` | Personal numbering services | | `PAGER` | Pager numbers | | `UAN` | Universal Access Numbers | | `VOICEMAIL` | Voicemail access numbers | | `UNKNOWN` | Type cannot be determined | ### Validation Errors | Error Code | Description | Example | | ---------------------- | -------------------------------- | ---------------------- | | `TOO_SHORT` | Number has too few digits | "123" in US | | `TOO_LONG` | Number has too many digits | "12345678901234" in US | | `INVALID_COUNTRY_CODE` | Country code not recognized | "+999 123456" | | `INVALID_LENGTH` | Doesn't match expected patterns | "1234567" in UK | | `NOT_A_NUMBER` | Not recognizable as phone number | "abc-defg" | ### Supported Regions Supports all countries with assigned telephone country codes: - **Americas**: US, CA, MX, BR, AR, CL, CO, PE, VE, etc. - **Europe**: GB, DE, FR, IT, ES, CH, NL, BE, SE, NO, DK, PL, etc. - **Asia-Pacific**: CN, JP, KR, IN, AU, NZ, SG, TH, MY, ID, PH, etc. - **Middle East & Africa**: AE, SA, IL, EG, ZA, NG, KE, MA, etc. - **And 200+ more regions** ### Use Cases - **E-commerce**: Validate customer phone numbers at checkout - **CRM Systems**: Clean and standardize phone number databases - **Marketing**: Verify phone numbers before SMS campaigns - **User Registration**: Validate phone numbers during sign-up - **Data Migration**: Format phone numbers consistently - **Lead Generation**: Verify collected phone numbers - **Customer Support**: Validate callback numbers ### Security & Privacy - No phone numbers are stored after processing - Results are kept in your private Apify dataset - Secure HTTPS API endpoints - Actor runs in isolated Docker containers - Compliant with data protection standards ### Error Handling The Actor handles errors gracefully: ```json { "success": false, "error": { "code": "PARSE_ERROR", "message": "Failed to parse phone number", "validationError": "NOT_A_NUMBER" } } ``` ### Examples #### Validate US Toll-Free Number ```json { "phoneNumbers": ["1-800-FLOWERS"], "defaultRegion": "US" } ``` #### Validate International Mobile ```json { "phoneNumbers": ["+44 7700 900123"], "defaultRegion": "GB" } ``` #### Batch Validation ```json { "phoneNumbers": [ "+33 6 12 34 56 78", "0412 345 678", "+81-3-1234-5678" ], "defaultRegion": "US" } ``` # Actor input Schema ## `phoneNumbers` (type: `array`): Enter phone numbers to validate ## `defaultRegion` (type: `string`): ISO 3166-1 alpha-2 country code for numbers without country code ## Actor input object example ```json { "phoneNumbers": [ "+1 650-253-0000", "+44 20 7183 8750" ], "defaultRegion": "US" } ``` # 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 = { "phoneNumbers": [ "+1 650-253-0000", "+44 20 7183 8750" ], "defaultRegion": "US" }; // Run the Actor and wait for it to finish const run = await client.actor("zenapi/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 = { "phoneNumbers": [ "+1 650-253-0000", "+44 20 7183 8750", ], "defaultRegion": "US", } # Run the Actor and wait for it to finish run = client.actor("zenapi/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 '{ "phoneNumbers": [ "+1 650-253-0000", "+44 20 7183 8750" ], "defaultRegion": "US" }' | apify call zenapi/phone-number-validator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=zenapi/phone-number-validator", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Phone Number Validator", "description": "A powerful Apify Actor for validating and parsing phone numbers from any country. Get instant validation results with detailed information including formatting options, number type classification, and metadata for phone numbers worldwide.", "version": "1.1", "x-build-id": "zJjb0D6Mpm0vk5bz7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/zenapi~phone-number-validator/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-zenapi-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/zenapi~phone-number-validator/runs": { "post": { "operationId": "runs-sync-zenapi-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/zenapi~phone-number-validator/run-sync": { "post": { "operationId": "run-sync-zenapi-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": { "phoneNumbers": { "title": "Phone Numbers", "type": "array", "description": "Enter phone numbers to validate", "items": { "type": "string" } }, "defaultRegion": { "title": "Default Region", "pattern": "^[A-Z]{2}$", "type": "string", "description": "ISO 3166-1 alpha-2 country code for numbers without country code", "default": "US" } } }, "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 } } } } } } } } } } ```