# NANP Phone Carrier & Line Type Validator (`jungle_synthesizer/localcallingguide-nanp-phone-carrier-line-type-validator`) Actor

Validate any NANP phone number and get back the real carrier of record, ILEC, rate centre, and a wireless-vs-landline flag from public numbering-plan data — plus local time and a TCPA calling-window check, not a format parse.

- **URL**: https://apify.com/jungle\_synthesizer/localcallingguide-nanp-phone-carrier-line-type-validator.md
- **Developed by:** [BowTiedRaccoon](https://apify.com/jungle_synthesizer) (community)
- **Categories:** Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.80 / 1,000 record scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Bulk Phone Number Carrier & Line Type Validator (NANP)

Validate US, Canadian, and wider NANP phone numbers and get back the carrier of record, not just a format check. Returns operating company, incumbent carrier, wireless-vs-landline classification, rate centre, local time, and a TCPA calling-window flag for every number you submit.

***

### Carrier Validator Features

- Numbering-plan validation for any country — `is_valid`, `is_possible`, `number_type`, `region_code`.
- Real carrier of record for NANP numbers — operating company name, OCN, and the incumbent carrier for that rate centre. Most "carrier lookup" tools stop at guessing from the area code.
- Wireless-vs-landline flag at the thousand-block level. That's the granularity carrier assignment actually happens at, so an NXX-level guess is wrong for any pooled prefix.
- TCPA calling-window check — local time at the number's rate centre, derived from real coordinates, plus a boolean for whether it's currently between 08:00 and 21:00 there.
- Dead-number signal — flags a thousand-block that's on file as disconnected.
- Honest confidence labels on every row (`exact_block`, `nxx_level`, `plan_only`) instead of pretending every answer is equally certain.

***

### Who Uses Phone Carrier & Line Type Data?

- **TCPA compliance reviewers** — confirm a number is wireless before a campaign treats it as landline, and check the calling window before a dial, not after a complaint.
- **SMS / outbound sales teams** — wireless vs. landline decides whether a text will even deliver. Knowing before you dial beats finding out from a bounce report.
- **CRM hygiene runs** — validate and enrich a phone column in the same pass you're already running an email or address cleanup in.
- **Lead-gen and list brokers** — attach a real carrier field to a list instead of the offline format guess every other tool ships.
- **Debt collection and skip-tracing shops** — the dead-number signal and portability caveat matter more here than almost anywhere else.

***

### How the Carrier Validator Works

1. Submit a list of phone numbers in any reasonable format — E.164, national, or a bare 10-digit NANP number.
2. Each number gets a full numbering-plan validation, then, for NANP numbers, the actor resolves the exact thousand-block that owns it against public NANP number-administration data.
3. Rate-centre coordinates feed a timezone lookup, which produces the number's local time right now and whether it falls inside the 08:00–21:00 calling window.
4. You get one row per input number, in the order you submitted them, with an honest confidence label on the carrier fields.

***

### Input

```json
{
  "phoneNumbers": [
    "+1 212-380-4567",
    "+1 800 555 0100",
    "not a phone number"
  ],
  "defaultRegion": "US",
  "maxItems": 15
}
```

| Field           | Type    | Default  | Description |
|-----------------|---------|----------|-------------|
| `phoneNumbers`  | array   | required | Phone numbers to validate. Any format works — E.164, national, or a bare 10-digit NANP number. |
| `defaultRegion` | enum    | `US`     | Region assumed for a number with no country code. `US` or `CA`. Only matters for national-format input. |
| `maxItems`      | integer | 15       | Hard cap on the number of phone numbers processed per run. |

***

### Carrier Validator Output Fields

```json
{
  "input": "+1 212-380-4567",
  "e164": "+12123804567",
  "country_code": "1",
  "national_number": "2123804567",
  "is_valid": true,
  "is_possible": true,
  "region_code": "US",
  "npa": "212",
  "nxx": "380",
  "thousand_block": "4",
  "number_type": "fixed_line",
  "is_toll_free": false,
  "toll_free_pattern": null,
  "carrier_ocn": "829J",
  "carrier_name": "PAETEC ITEL, LLC",
  "carrier_type": "CLEC",
  "ilec_ocn": "9104",
  "ilec_name": "VERIZON NEW YORK, INC.",
  "is_wireless_block": false,
  "is_voip_block": false,
  "rate_center": "New York City Zone 01",
  "rate_center_state": "NY",
  "lata": "132",
  "switch_clli": "NYCMNYBXX6X",
  "switch_type": "POI",
  "rate_center_lat": 40.739362,
  "rate_center_lon": -73.991043,
  "timezone": "America/New_York",
  "utc_offset": -4,
  "local_time_now": "2026-09-28T15:42:00",
  "is_within_calling_window": true,
  "block_effective_date": null,
  "block_disconnect_date": null,
  "is_disconnected_block": false,
  "assignment_last_updated": "2026-09-01",
  "carrier_confidence": "exact_block",
  "portability_caveat": true,
  "validation_reasons": ["POSSIBLE_LENGTH_OK", "NUMBERING_PLAN_VALID", "NANP_DECOMPOSED", "CARRIER_BLOCK_EXACT"]
}
```

| Field                                 | Type    | Description |
|---------------------------------------|---------|--------------|
| `input`                               | string  | Original input string, as supplied. |
| `e164`                                | string  | Normalised `+1NPANXXXXXX` form. Null when the number doesn't validate. |
| `country_code`                        | string  | Country calling code — `"1"` for every NANP member. |
| `national_number`                     | string  | National significant number, digits only. |
| `is_valid`                            | boolean | Numbering-plan validity — not "does it ring." |
| `is_possible`                         | boolean | True when the number has a plausible length for its region. |
| `region_code`                         | string  | ISO2 territory — `US`, `CA`, `PR`, `VI`, `GU`, `AS`, `MP`, `BS`, `BB`, `JM`, and other NANP members. |
| `npa`                                 | string  | Area code (NANP numbers only). |
| `nxx`                                 | string  | Central-office/exchange code (NANP numbers only). |
| `thousand_block`                      | string  | The 7th digit — carrier assignment happens at this level, not the NXX. |
| `number_type`                         | string  | `fixed_line`, `mobile`, `fixed_or_mobile`, `voip`, `toll_free`, `premium`, `shared_cost`, `pager`, or `uan`. |
| `is_toll_free`                        | boolean | True for the seven NANP toll-free area codes. |
| `toll_free_pattern`                   | string  | Which toll-free area code matched (`800`, `833`, `844`, `855`, `866`, `877`, `888`). |
| `carrier_ocn`                         | string  | Operating Company Number — the carrier identifier of record. |
| `carrier_name`                        | string  | Carrier name of record for this thousand-block. |
| `carrier_type`                        | string  | `ILEC`, `CLEC`, `wireless`, or `VoIP-interconnected`. |
| `ilec_ocn`                            | string  | Incumbent carrier's OCN for this rate centre. |
| `ilec_name`                           | string  | Incumbent carrier name for this rate centre. |
| `is_wireless_block`                   | boolean | True when the block is assigned to a wireless carrier — the TCPA-relevant flag. |
| `is_voip_block`                       | boolean | True when the block is assigned to a VoIP-interconnected CLEC. |
| `rate_center`                         | string  | Rate centre name. |
| `rate_center_state`                   | string  | State/province/territory of the rate centre. |
| `lata`                                | string  | Local Access and Transport Area code. |
| `switch_clli`                         | string  | Common Language Location Identifier of the serving switch. |
| `switch_type`                         | string  | Switch/office type code. |
| `rate_center_lat` / `rate_center_lon` | number  | Rate centre coordinates. |
| `timezone`                            | string  | IANA timezone derived from the rate centre's coordinates. |
| `utc_offset`                          | number  | Current UTC offset (hours) for that timezone. |
| `local_time_now`                      | string  | Current local time at the rate centre — the field an outbound dialer actually needs. |
| `is_within_calling_window`            | boolean | True between 08:00 and 21:00 local time — the TCPA calling-window check. |
| `block_effective_date`                | string  | Date this block assignment took effect, when published. |
| `block_disconnect_date`               | string  | Date this block was disconnected — a dead-number tell. Null if still active. |
| `is_disconnected_block`               | boolean | True when a disconnect date is on file for this block. |
| `assignment_last_updated`             | string  | Date the underlying record for this block was last updated. |
| `carrier_confidence`                  | string  | `exact_block`, `nxx_level`, or `plan_only` — honest about how granular the carrier match is. |
| `portability_caveat`                  | boolean | True whenever carrier data is returned — a ported number's block carrier is the original assignee, not necessarily the current one. |
| `validation_reasons`                  | array   | Rule ids behind `is_valid` / `number_type` / `carrier_confidence` — auditable, not a black box. |
| `scraped_at`                          | string  | When this record was produced. |

***

### FAQ

#### How do I look up the carrier for a phone number?

Pass it in `phoneNumbers` in any reasonable format. The validator returns the carrier of record, the incumbent carrier, and a wireless-vs-landline flag in the same row as the standard numbering-plan checks.

#### Does this work for Canadian numbers?

Yes — NANP covers the US, Canada, and a handful of Caribbean members, and all of them share the same numbering structure. Set `defaultRegion` to `CA` if you're passing bare national-format numbers without a country code.

#### What does `carrier_confidence` actually mean?

`exact_block` means the answer is specific to your number's exact thousand-block. `nxx_level` means the whole exchange is assigned to one carrier so there's no finer distinction to make. `plan_only` means there's no carrier assignment on file — either the number is outside NANP, or the prefix is unassigned or reserved.

#### Can I tell if a number is a landline or a cell phone?

That's `is_wireless_block`. Most numbering-plan-only validators can't answer this for NANP numbers at all — the plan itself doesn't separate mobile ranges the way many other countries do, so this validator answers it from the carrier assignment instead.

#### Do I need an account or API key?

No. Submit numbers and get results — no signup, no key, no per-number vendor fee.

***

### Need More Features?

Need a different field, a bulk-file input, or coverage beyond NANP? [File an issue](https://console.apify.com/actors/issues) or get in touch.

### Why Use This Carrier Validator?

- **Answers the question everyone else guesses at** — real carrier of record, not a format parse dressed up as one.
- **Built for the compliance use case, not just the sales one** — the wireless flag and calling-window boolean are the two facts a TCPA-conscious dialer actually needs, computed together instead of pieced together from two tools.
- **Says what it doesn't know** — a ported number, an unassigned prefix, or a non-NANP number all come back with an honest confidence label instead of a confident-looking wrong answer.

# Actor input Schema

## `sp_intended_usage` (type: `string`):

What will this data feed? E.g. lead lists, KYB checks, price tracking.

## `sp_improvement_suggestions` (type: `string`):

Provide any feedback or suggestions for improvements.

## `sp_contact` (type: `string`):

We'll personally help with your use case. No spam.

## `phoneNumbers` (type: `array`):

Phone numbers to validate. Any format works — E.164 (+1 212-380-4567), national, or a bare 10-digit NANP number.

## `defaultRegion` (type: `string`):

Region assumed for a number with no country code. Only used to disambiguate national-format input.

## `maxItems` (type: `integer`):

Hard cap on the number of phone numbers processed per run.

## Actor input object example

```json
{
  "sp_intended_usage": "Describe your intended use...",
  "sp_improvement_suggestions": "Share your suggestions here...",
  "sp_contact": "Share your email here...",
  "phoneNumbers": [
    "+1 212-380-4567",
    "+1 800 555 0100",
    "not a phone number"
  ],
  "defaultRegion": "US",
  "maxItems": 15
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "sp_intended_usage": "Describe your intended use...",
    "sp_improvement_suggestions": "Share your suggestions here...",
    "sp_contact": "Share your email here...",
    "phoneNumbers": [
        "+1 212-380-4567",
        "+1 800 555 0100",
        "not a phone number"
    ],
    "defaultRegion": "US",
    "maxItems": 15
};

// Run the Actor and wait for it to finish
const run = await client.actor("jungle_synthesizer/localcallingguide-nanp-phone-carrier-line-type-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "sp_intended_usage": "Describe your intended use...",
    "sp_improvement_suggestions": "Share your suggestions here...",
    "sp_contact": "Share your email here...",
    "phoneNumbers": [
        "+1 212-380-4567",
        "+1 800 555 0100",
        "not a phone number",
    ],
    "defaultRegion": "US",
    "maxItems": 15,
}

# Run the Actor and wait for it to finish
run = client.actor("jungle_synthesizer/localcallingguide-nanp-phone-carrier-line-type-validator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "sp_intended_usage": "Describe your intended use...",
  "sp_improvement_suggestions": "Share your suggestions here...",
  "sp_contact": "Share your email here...",
  "phoneNumbers": [
    "+1 212-380-4567",
    "+1 800 555 0100",
    "not a phone number"
  ],
  "defaultRegion": "US",
  "maxItems": 15
}' |
apify call jungle_synthesizer/localcallingguide-nanp-phone-carrier-line-type-validator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jungle_synthesizer/localcallingguide-nanp-phone-carrier-line-type-validator"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/mtBcLGGlcgVEE2nJm/builds/yBpnqWfTpenwaM8UY/openapi.json