Phone Number Wrangler

Phone Number Wrangler is a batch phone-number-processing toolkit for the Apify platform, built on Google's libphonenumber via the phonenumbers Python port. Feed it a list of phone numbers and pick one of four operations — validate, format, parse (full breakdown), or extract a single field — and get structured JSON back, one row per input number. Run it via the Apify Console, the API, or on a schedule, with full run history, monitoring, and integrations (Zapier, Make, Google Sheets, webhooks) included.

Why use Phone Number Wrangler?

Cleaning up phone numbers scraped from a website, validating leads before a dialer campaign, or normalizing a CRM export usually means pulling in phonenumbers yourself and writing glue code around it. Phone Number Wrangler packages the common operations into a single Actor so you can:

• Validate leads in bulk before handing them to a dialer or SMS provider (validate) — get valid/possible flags plus a canonical E.164 form.
• Normalize numbers to a consistent format for storage or deduplication (format) — E.164, international, national, or RFC 3966 (tel: URI).
• Get a full breakdown of every number — country code, national significant number, region, line type (mobile/fixed/toll-free/VOIP/...), carrier, approximate location, and timezone(s) (parse).
• Pull out just one field — e.g. only the region code or only the carrier — from a batch of numbers for reporting or filtering (extract).

How to use Phone Number Wrangler

1. Open the Actor's Input tab.
2. Choose an Operation: validate, format, parse, or extract.
3. Paste your list of phone numbers into Phone numbers.
4. If any number isn't already in +-prefixed international form, set Default region (e.g. US) so it can be interpreted correctly.
5. Fill in the fields relevant to your chosen operation (see Input below, and Examples for a full input/output pair per operation — irrelevant fields are ignored).
6. Click Start. Results land in the run's default Dataset, one row per input number, downloadable as JSON, CSV, Excel, or HTML.

Input

All fields live in one flat input object — an operation selector, the shared numbers list, and a handful of operation-specific parameters that apply uniformly to every number in that run. See the Input tab for the full schema with descriptions.

Field	Used by	Description
operation	all	validate | format | parse | extract
numbers	all	The phone numbers to process
defaultRegion	all	Two-letter region code (e.g. US, GB) used to interpret numbers not already in +-prefixed international form
format	format	E164 | INTERNATIONAL | NATIONAL | RFC3966
field	extract	country_code | national_number | extension | region_code | number_type | carrier | location | timezones
language	parse, extract (field=carrier/location)	Two-letter language code for carrier name and geographic description

Output

Every run pushes one dataset item per input number: { operation, input, result, error }. error is null on success, so a single malformed number never aborts the run.

Examples

Each pair below is a complete Actor input alongside the corresponding dataset row it produces.

validate

Input:

{
  "operation": "validate",
  "numbers": ["+14155552671", "+1234"]
}

Output (first row):

{
  "operation": "validate",
  "input": "+14155552671",
  "result": { "valid": true, "possible": true, "e164": "+14155552671" },
  "error": null
}

format

Input:

{
  "operation": "format",
  "numbers": ["(415) 555-2671"],
  "defaultRegion": "US",
  "format": "RFC3966"
}

Output:

{
  "operation": "format",
  "input": "(415) 555-2671",
  "result": "tel:+1-415-555-2671",
  "error": null
}

parse

Input:

{
  "operation": "parse",
  "numbers": ["+14155552671"]
}

Output:

{
  "operation": "parse",
  "input": "+14155552671",
  "result": {
    "valid": true,
    "possible": true,
    "country_code": 1,
    "national_number": "4155552671",
    "extension": null,
    "region_code": "US",
    "number_type": "FIXED_LINE_OR_MOBILE",
    "e164": "+14155552671",
    "international": "+1 415-555-2671",
    "national": "(415) 555-2671",
    "rfc3966": "tel:+1-415-555-2671",
    "carrier": null,
    "location": "San Francisco, CA",
    "timezones": ["America/Los_Angeles"]
  },
  "error": null
}

extract

Input:

{
  "operation": "extract",
  "numbers": ["+14155552671"],
  "field": "number_type"
}

Output:

{
  "operation": "extract",
  "input": "+14155552671",
  "result": "FIXED_LINE_OR_MOBILE",
  "error": null
}

Data table

Field	Type	Present when	Description
operation	string	always	Operation that produced this row
input	string	always	The original input phone number
result	varies	on success	Validation object (validate), formatted string (format), full breakdown object (parse), or field value (extract)
error	string | null	always	Failure reason for this number, or null

Pricing / cost estimation

Phone Number Wrangler does pure in-memory number parsing against a bundled metadata database — no network requests, no browser, no proxy usage. Cost is driven entirely by compute time, which is minimal (typically well under 100ms per number). On the Apify Free plan, you can process tens of thousands of numbers per run within the platform's free monthly compute unit allowance.

Tips / advanced options

• Numbers already in +-prefixed international form (e.g. +14155552671) don't need defaultRegion — it's only used to interpret national-format numbers like (415) 555-2671.
• carrier and location lookups mainly cover mobile numbers in supported countries; landlines and some regions legitimately return null.
• number_type values follow libphonenumber's own enum: FIXED_LINE, MOBILE, FIXED_LINE_OR_MOBILE, TOLL_FREE, PREMIUM_RATE, SHARED_COST, VOIP, PERSONAL_NUMBER, PAGER, UAN, VOICEMAIL, UNKNOWN.
• validate's possible flag is a cheaper length/prefix sanity check; valid runs the full metadata-backed validation and is stricter.

Background reading

This Actor is a thin wrapper around Google's libphonenumber. Related reading:

• google/libphonenumber — the canonical phone-number handling library this Actor is built on
• daviddrysdale/python-phonenumbers — the Python port (phonenumbers on PyPI) used here
• E.164 (Wikipedia) — the international public telecommunication numbering plan format
• ITU-T Recommendation E.164 — the official numbering plan spec this format is named after

FAQ, limitations, and support

• This Actor only processes phone numbers you provide — it does not dial, send SMS, or contact any number.
• Metadata (valid ranges, carrier names, geographic descriptions) comes bundled with the phonenumbers library version pinned in this Actor and is refreshed on dependency updates, not in real time.
• Found a bug or want another operation (bulk deduplication, country-code presets, custom formatting)? Open an issue on the Actor's Issues tab — these are tracked as candidate follow-ups.

Data pipeline toolkit

Part of the Data pipeline toolkit — small, chainable Actors for cleaning, transforming, and generating data inside a larger pipeline:

• jq Helper – transform JSON with jq — Run jq programs over inline JSON or a linked Apify dataset.
• DuckDB Helper – SQL over CSV, JSON, Parquet, Excel, SQLite — Run a DuckDB SQL query over remote/local files, push results to a dataset.
• Regex Helper — Apply named regular expressions to strings, extract structured matches.
• URL Wrangler — Join, decompose, and rewrite URLs and query params in batch.
• ZIP Code Helper — Resolves US ZIP codes into city, state, county, and more.
• Postal Address Normaliser — Parses and normalises postal addresses using libpostal.
• UUID Generator — Generate bulk UUIDs (v1, v3, v4, v5, v7) on demand.
• Secure Password & Passphrase Generator — Generate secure passwords and diceware passphrases per NIST guidance.
• Thumbnail Maker — Generates thumbnails from image URLs using ImageMagick.
• Katana Web Crawler (ProjectDiscovery) — Crawl websites with Katana, stream results as JSONL.
• ProjectDiscovery Notify — Stream records to Slack, Discord, Telegram, Email, and more.

Did you find this useful?

⭐ Rate this actor on Apify! Your feedback helps other users find it and helps us keep improving it.