Phone Number Validator & Formatter | Carrier Data

Turn inconsistent phone lists or CSV files into structured records for CRM imports, contact cleanup and reporting. Validate numbering patterns, normalize formats, and enrich each entry with available country, number-type, original-carrier and numbering-area metadata.

Phone-number processing runs locally inside the Actor using Google's libphonenumber metadata through its Python port. No phone-lookup API key, proxy, phone call or SMS is required. CSV URLs are downloaded over the network, and Apify storage and exports are used to deliver your results.

What you get

• Number validation: separate valid and possible flags, with readable reason codes for entries that do not pass validation.
• Standard formats: E.164, international, national and RFC3966 tel: URI, with extensions preserved separately.
• Number classification: mobile, fixed line, fixed-line-or-mobile, VoIP, toll-free, premium-rate and other supported types.
• Available metadata: country/region, calling code, numbering-area label, original carrier and possible time zones.
• Flexible batch input: use a number list, a CSV download URL, or both. Select the CSV column and optionally cap the combined result count.
• Complete validation output: one row per selected entry, including invalid numbers. Input order and duplicate entries are preserved; empty CSV phone cells are skipped.
• Clear metadata availability: carrier availability, a note when carrier metadata is missing, and a UTC processing timestamp for every result.
• Apify exports: JSON, CSV and Excel through the Dataset, plus a separate run summary.

Validation is not a live verification. A valid number matches the library's numbering-plan rules; it does not prove that the number is assigned, active, reachable or owned by a particular person. Carrier and location fields are offline metadata, not a live carrier query or device location.

Common use cases

• Clean and standardize phone columns before CRM or contact-database imports.
• Convert international and national inputs into consistent E.164 values for APIs and automation workflows.
• Separate mobile, fixed-line, VoIP, toll-free and other supported number types for routing or list review.
• Audit CSV lead lists without dropping invalid rows, so every processed input keeps a visible validation result.
• Add country, calling-code, numbering-area, original-carrier and time-zone metadata to internal data pipelines.

Quick start

1. Enter one phone number per item in Phone numbers, or provide a CSV file URL and its phone-number column name.
2. Use + and the country calling code for international numbers. For national numbers, set the corresponding Default region, such as CN, US or GB.
3. Run the Actor and open Phone validation results. Download the full Dataset in your preferred format.

{
  "phoneNumbers": ["+44 20 7946 0958", "+1 202 555 0100"],
  "language": "en"
}

These are example entries, not customer data or a claim that the numbers are active. To parse a UK national number, pass "defaultRegion": "GB" and an entry such as "020 7946 0958".

Input

Field	Required	Meaning
phoneNumbers	One source required	Array of strings, one number per item. Optional when csvUrl is supplied. Spaces, parentheses, extensions and other library-supported formatting are handled by the parser.
csvUrl	One source required	Direct HTTP or HTTPS download URL for a UTF-8, comma-separated CSV file with a header row. Optional when phoneNumbers is supplied. The URL must work without a separate login.
csvColumn	No	Exact, case-sensitive CSV header containing the numbers. Defaults to phone; used only with csvUrl. Other CSV columns are not copied to the output.
defaultRegion	No	Two-letter region code for numbers without a + country code. Empty by default: the Actor does not assume a country. Use GB, not UK, and US, not USA.
maxResults	No	Positive integer limiting the combined number of entries to process. Omit it to process all entries. Invalid entries and duplicates also count toward the limit.
language	No	Preferred language for country, area and original-carrier labels. Defaults to en; zh selects Chinese labels where available. Missing selected-language labels fall back to available English metadata. It does not change validation or number formats, and does not translate JSON field names, status values, reason codes or explanatory notes.

For mixed-country lists, use + international numbers. Dialing prefixes such as 00 and 011 depend on the default region; the Actor does not globally replace them with +. Short codes and emergency numbers are not part of this full-length phone-number validator.

Provide phoneNumbers, csvUrl, or both. When both are supplied, inline entries are processed first, followed by CSV entries in file order. If the inline list already fills maxResults, the CSV is not downloaded. Otherwise, CSV reading stops when the remaining result limit is reached. Empty or whitespace-only CSV phone cells are skipped; non-empty but invalid entries still produce a result.

CSV example

{
  "csvUrl": "https://example.com/phones.csv",
  "csvColumn": "phone",
  "maxResults": 1000,
  "language": "en"
}

Replace the placeholder URL above with your own CSV download URL. A matching file could contain:

phone
+44 20 7946 0958
+1 202 555 0100

CSV files must use UTF-8 (with or without a BOM), commas as separators, and a header row. A webpage or file-sharing preview link is not a direct CSV download. This Actor does not parse Excel files, extract numbers from website text or paragraphs, remove duplicates, or filter out invalid entries.

Invalid run-level settings fail with a clear message before results are treated as complete. This includes a missing input source, unsupported defaultRegion or language, a non-HTTP(S) or inaccessible CSV URL, non-UTF-8 CSV content, and a csvColumn header that is not present. Missing phone metadata inside an otherwise valid result still follows the output rule and uses "".

Output

The main table shows the original number, validation status, E.164, country/region, number type, numbering area, original carrier and reason. The Formats and metadata view shows additional formats, time zones, carrier availability and processing time. Full JSON contains all 20 fields below.

Field	Meaning
input	Original input entry.
status	valid, possible or invalid. possible means it passes a length-based possibility check but not full validation.
valid	Whether the number matches supported numbering-plan validation rules.
possible	The library's length-based possibility result; it can also be true for locally dialable numbers missing an area code.
reason	"" for valid numbers; otherwise a reason such as too_short, possible_but_invalid, possible_local_only, not_a_number or missing_or_invalid_country_code.
e164	Normalized + international form; extensions are not included.
international	Readable international format.
national	Readable national format.
rfc3966	tel: URI, including an extension when present.
extension	Parsed extension, or "".
countryCode	Detected region code; 001 denotes a non-geographic calling service, not a country. "" if undetermined.
countryCallingCode	Integer international calling code, such as 44, or "" when unavailable.
countryName	Available country name for a valid number, or "".
location	Available numbering-area or country label for a valid number, not the subscriber's current location.
numberType	Lowercase library classification, such as mobile, fixed_line or fixed_line_or_mobile. unknown is an explicit classification, not a missing value.
originalCarrier	Available original carrier associated with the number range, not necessarily the current carrier after number portability.
timeZones	Array of possible time-zone names from metadata for valid numbers; "" when unavailable.
carrierAvailable	Boolean indicating whether originalCarrier contains metadata. false does not mean the number is inactive.
carrierLookupNote	Short explanation when carrier data is unavailable, validation was skipped, or the displayed carrier uses an English fallback. Usually "" when the selected-language carrier label is available.
validatedAt	UTC timestamp in ISO 8601 format for this entry's processing. It is not a live network-verification timestamp.

Missing values are returned as "", not null or an empty array. Meaningful false flags, numeric 0 counts and populated arrays retain their types. Unparseable inputs keep the same field structure with empty-string formats. A parseable but invalid number may still have formatted candidate values: filter on valid: true before treating a formatted number as a validated entry.

The Validation summary record includes selected input and processed counts, valid/possible-only/invalid totals, number-type counts, selected region/language and the library version used. Counts include duplicates. Its inputSelection section records inline entries supplied and selected, CSV rows actually read, CSV numbers loaded, empty CSV cells skipped, the chosen limit and whether the CSV was skipped because inline entries filled that limit. When reading stops early, these CSV counts are not totals for the entire file. limitReached means the selected count reached maxResults; it does not prove that more entries existed.

Billing unit

Under pay-per-event pricing, each selected phone entry successfully written to the Dataset creates one phone-number-processed event. The current flat price is $0.0005 per result, or $0.50 per 1,000 processed numbers. Valid, possible-only and invalid results are all billable because each receives validation and formatting analysis. Empty CSV phone cells, entries not processed because the run charge limit was reached, and runs that fail during input or CSV validation do not create this event. Apify shows the active event and Actor-start prices before a paid run starts.

Common questions

Can it identify the owner or check WhatsApp registration?

No. It does not look up names, accounts, messaging-app registration, subscriber records or breach data.

Does “valid” mean a number can receive SMS or calls?

No. The Actor performs offline numbering-plan validation. It does not contact the number or verify service availability. A number type is not a delivery guarantee.

Why is the type fixed_line_or_mobile or the carrier empty?

Some numbering plans do not distinguish fixed and mobile services by prefix. Carrier metadata is also not available for every number range. The Actor preserves this uncertainty.

Why did a national number fail?

Set defaultRegion to the region the national number belongs to, or provide the + international form. The Actor does not guess missing country or area codes.

Does language translate every result field?

No. It selects the best available language for countryName, location and originalCarrier. Translation coverage varies by country and number range. When a selected-language label is unavailable, available English metadata is returned; carrierLookupNote identifies an explicit carrier fallback. A localized area may fall back to a localized country name when no translated city or region label exists. Validation fields, formats and Actor explanations stay in English.

Do invalid numbers disappear from the output?

No. They are useful data-cleaning results and remain in the Dataset with a reason. A run can succeed even when some or all input numbers are invalid.

Use with the Apify API

Use an Apify API token with access to this Actor. Phone validation itself does not need a separate provider key.

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("arjun_code/phone-number-validator").call(
    run_input={
        "phoneNumbers": ["+44 20 7946 0958", "+1 202 555 0100"],
        "language": "en",
    }
)
for result in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(result)

Open-source attribution

Powered by Google libphonenumber via python-phonenumbers, an independently maintained Python port listed by the upstream project. This Actor wraps the library without modifying it. Third-party licenses and attribution are retained with the packaged dependencies and documented in THIRD_PARTY_NOTICES.md.

Use phone data you are authorized to process. Input and output are stored in your Apify run and storages; manage their sharing permissions in your account.