Phone Number Validator

Validate up to 1,000 phone numbers in one run and get each number's line type, region, carrier, timezones and every standard format, with no network lookup and no per-number upstream fee.

What you get

One dataset item per number you send. Here is one of them, for input +1 415-555-2671:

{
  "input": "+1 415-555-2671",
  "valid": true,
  "possible": true,
  "e164": "+14155552671",
  "formats": {
    "international": "+1 415 555 2671",
    "national": "(415) 555-2671",
    "rfc3966": "tel:+14155552671"
  },
  "region": "US",
  "regionName": "United States",
  "countryCode": 1,
  "type": "fixed_line_or_mobile",
  "carrier": null,
  "carrierConfidence": null,
  "timezones": ["America/Los_Angeles"],
  "reasonCode": "valid"
}

Use it when

• You are cleaning a lead or contact list before it gets dialed, texted, or loaded into a CRM.
• You need one canonical form of a number (E.164) for deduplication or storage.
• You are routing by line type, and want to skip premium-rate or toll-free numbers before you pay to send anything.
• You are scheduling calls and need the number's timezones.
• An agent is validating a list and needs a stable, typed answer per row.

Input

Field	Type	Required	What it does
phones	array of strings	yes	The raw numbers in any common format, up to 1,000 per run. A tel: prefix is accepted. Each distinct number gets one dataset item and one charge. The same digits written differently (+1 (415) 555-2671, tel:+14155552671) count once.
defaultRegion	ISO-3166 alpha-2 string	no	The country assumed for numbers with no leading +, for example US. Ignored for numbers already in E.164 form. Case does not matter.

defaultRegion is a run-wide setting: it applies to every number in the batch, not to one of them. A list pasted out of a CRM is usually all from one country, which is the case it serves. If yours is not, split the numbers across runs.

A number written without a + and without a defaultRegion cannot be resolved to any country, so it comes back as ambiguous_no_region rather than a guess.

A number written with a leading 00 is treated the same way unless 00 is the international prefix of the defaultRegion. In much of the world 00 means "dial international". Elsewhere it is part of the number: the NANP dials 011 for international, and Russia dialled 810. So 0044 7400 123456 is answered under GB, and under US it comes back ambiguous_idd_prefix, free of charge. Guessing would invent a country code. Calling it invalid would delete a real number from your list.

Output

Field	What it means
valid	The number fits the numbering plan of its region.
possible	The length is plausible for the region, a weaker check than valid.
e164, formats	Canonical forms. All null unless the number is valid, so an invalid number never produces a dialable-looking string.
region, regionName, countryCode	ISO country, English country name, calling code.
type	mobile, fixed_line, fixed_line_or_mobile, voip, toll_free, premium_rate, shared_cost, pager, personal_number, uan, or unknown.
carrier, carrierConfidence	The carrier the number block was allocated to. carrierConfidence is always prefix-based when a carrier is present.
timezones	IANA timezone names for the number's area.
reasonCode	valid, invalid_length, invalid_country_code, not_assigned, impossible, not_a_number, ambiguous_no_region, ambiguous_idd_prefix, or unknown_region.

Pricing

Pay per event, $2.00 per 1,000 validated numbers ($0.002 each), charged on the phone-validated event.

A number that comes back conclusively invalid is charged like a valid one, because a list-cleaning job is buying both answers. A non-answer is never charged:

reasonCode	Charged
valid, invalid_length, invalid_country_code, not_assigned, impossible	yes
not_a_number (input is not a number at all)	no
ambiguous_no_region (no +, no defaultRegion)	no
ambiguous_idd_prefix (leading 00 that this region doesn't dial international with)	no
unknown_region (defaultRegion is not a real country code, and the number needed it)	no

If you set a maximum total charge for a run, the Actor stops as soon as that limit is reached instead of working for free. Items after that point are left out of the dataset and not charged, and the run log says how many; submit them in a new run.

What this does not do

valid means the number conforms to its country's numbering plan. It does not mean somebody answers it. Nothing here dials, rings, or sends anything.

Carrier comes from the number block's allocation, so a ported number reports the carrier that originally held the block. Line type is unknown for countries whose numbering plan does not separate mobile from fixed line.

There is no lookup of a subscriber name, and no HLR query.

How it works

The Actor bundles Google's libphonenumber metadata, with the full range data rather than the trimmed set, plus its offline carrier and timezone data files. It makes no network requests at all, so there is nothing to rate limit and no upstream that can be down.

One verdict per number

Numbers are validated in the order you send them, each written as its own dataset item. There is no start fee, so a list of 1,000 numbers pays one container start for the whole run instead of one per number:

const run = await client.actor('pontio/validate-phone').call({
  phones: ['+1 415-555-2671', '(415) 555-2671'],
  defaultRegion: 'US',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();

If you set a maximum charge for the run and the batch reaches it, the run stops there rather than carrying on with work it cannot charge for. A run that reaches its timeout stops the same way. Either way the items already written stay in the dataset, and each names what it answers, so you can re-run the remainder.