# Live Phone Intelligence — Carrier, Portability & Reachability (`tryva/phone-intelligence-v2`) Actor

Live telecom evidence — not just an offline format check. Validate and normalize phone numbers, get current carrier/network, ported status and network reachability, then return an explainable ACCEPT / REVIEW / REJECT decision.

- **URL**: https://apify.com/tryva/phone-intelligence-v2.md
- **Developed by:** [smile flow](https://apify.com/tryva) (community)
- **Categories:** Developer tools
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $50.00 / 1,000 live phone intelligences

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Live Phone Validator & Carrier Intelligence — Portability + Reachability

> **Stop treating “valid” as “reachable.”**

Know if a phone number is structurally valid, **which network serves it now**, whether it has been **ported**, and whether the mobile network is currently **reachable** — then get an explainable `ACCEPT / REVIEW / REJECT` decision.

**No upstream telecom API key is required from marketplace users.**

### One request

```json
{
  "phone": "+14155552671",
  "expected_country": "US",
  "live": true,
  "require_reachable": true
}
```

### One decision-ready response

```json
{
  "static": {
    "valid": true,
    "possible": true,
    "e164": "+14155552671",
    "country": "US",
    "line_type": "fixed_or_mobile"
  },
  "live": {
    "evidence_status": "ok",
    "current_carrier": "Example Mobile",
    "current_network_code": "310260",
    "ported": false,
    "network_reachability": "reachable",
    "reachability_scope": "mobile_network",
    "observed_at": "2026-09-06T16:03:10.000Z"
  },
  "decision": "ACCEPT",
  "reason_codes": ["VALID_POLICY_MATCH"]
}
```

*Carrier/network values above are illustrative.*

### Why not a normal phone validator?

Offline validators such as `libphonenumber` are excellent for:

- parsing
- E.164 formatting
- possible/valid checks
- country
- line type
- numbering-plan metadata

But numbering-plan carrier metadata is **not the same thing as the carrier serving a ported number today**.

This product adds live HLR/MNP evidence after the static precheck:

```text
phone
  ↓
libphonenumber
  ↓
valid + normalized + line type
  ↓
live telecom evidence
  ↓
current network + ported + reachability
  ↓
policy
  ↓
ACCEPT / REVIEW / REJECT
```

### What you get

| Signal | Meaning |
|---|---|
| `e164` | Normalized international number |
| `valid` | Numbering-plan validity |
| `possible` | Length/structure plausibility |
| `country` | Parsed country/region |
| `line_type` | Mobile, landline, VoIP, etc. when detectable |
| `carrier_metadata` | Offline numbering-plan carrier metadata |
| `current_carrier` | Current serving carrier/network when live evidence is available |
| `current_network_code` | MCC/MNC-style network identifier when available |
| `ported` | Explicit portability status when available |
| `network_reachability` | Reachable / unreachable / unknown |
| `observed_at` | Timestamp for live evidence |
| `evidence_status` | Whether live evidence was successfully obtained |
| `decision` | `ACCEPT / REVIEW / REJECT` |
| `reason_codes` | Explainable reasons behind the decision |

### Built for real workflows

#### Lead validation & CRM hygiene

Normalize incoming numbers, reject structurally bad data, and flag records whose live telecom evidence requires review.

#### SMS / voice routing

Use current network and reachability evidence before spending on downstream messaging or calling.

#### Signup & onboarding

Apply country, line-type, portability, and reachability policies without inventing your own telecom logic.

#### Automation & AI agents

Give workflows a structured result plus a deterministic decision instead of asking an agent to interpret raw HLR/MNP payloads.

#### Batch enrichment

Analyze up to **100 numbers per request** using the same response contract as single-number lookups.

### Static vs live

#### Static preflight

`live: false`

Uses `libphonenumber` only.

Best for:

- normalization;
- format/validity checks;
- country;
- line type;
- inexpensive pre-filtering.

On Apify, static requests do **not** trigger the custom `live-phone-intelligence` event.

#### Live intelligence

`live: true`

Adds:

- current carrier/network;
- portability evidence;
- network reachability;
- observation timestamp.

Use live mode only when the workflow actually needs current telecom evidence.

### Optional decision policies

#### Require a country

```json
{
  "phone": "+33612345678",
  "expected_country": "US"
}
```

Result: `REVIEW` with `COUNTRY_MISMATCH`.

#### Require network reachability

```json
{
  "phone": "+14155552671",
  "live": true,
  "require_reachable": true
}
```

- reachable → policy can remain `ACCEPT`
- unreachable → `REVIEW`
- unknown → `REVIEW`

#### Review ported numbers

```json
{
  "phone": "+14155552671",
  "live": true,
  "review_if_ported": true
}
```

A confirmed ported number becomes `REVIEW` with a reason code.

### Important semantics

This API deliberately keeps these concepts separate:

```text
valid
≠ active subscriber
≠ network reachable
≠ SMS deliverable
≠ call answered
≠ identity verified
```

We return `unknown` when the evidence does not support a definitive answer.

We do **not** claim that a reachable network guarantees SMS delivery, call answer, ownership, identity, or absence of fraud.

### API

```text
GET  /health

POST /v2/phone/intelligence

POST /v2/phone/intelligence/batch
```

FastAPI also exposes interactive OpenAPI documentation at `/docs`.

### Pricing candidate

**$0.05 per successful live phone-intelligence decision**

The live event includes the premium telecom lookup and decision layer.

Static preflight remains a separate low-cost path and does not trigger the live custom event.

This is the validated launch price for the live intelligence event.

### Release status

**Private preview.**

Verified today:

- deterministic V1/static layer;
- live HLR lookup;
- live MNP lookup;
- current-carrier/network evidence;
- explicit ported boolean;
- network reachability;
- full CI;
- private Apify build.

Marketplace publication remains blocked until upstream redistribution/resale rights for our normalized derived outputs are confirmed.

# Actor input Schema

## Actor input object example

```json
{}
```

# Actor output Schema

## `dataset` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("tryva/phone-intelligence-v2").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("tryva/phone-intelligence-v2").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 '{}' |
apify call tryva/phone-intelligence-v2 --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tryva/phone-intelligence-v2"
        }
    }
}

```

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/fawrwURwEThZeiwkc/builds/35hiueQ26Q1nRdtOe/openapi.json