# Reverse Phone Lookup — Phone OSINT, Carrier & Spam Check (`ntriqpro/reverse-phone-lookup`) Actor

Reverse phone lookup for any number: carrier, line type, region, time zones, VoIP and premium-rate risk, plus public community spam and scam reports. One input number returns one verdict row and one row per signal found. Bulk input, no API keys.

- **URL**: https://apify.com/ntriqpro/reverse-phone-lookup.md
- **Developed by:** [Daniel Carter](https://apify.com/ntriqpro) (community)
- **Categories:** Developer tools, Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 number-checkeds

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

### What does Reverse Phone Lookup do?

**Reverse Phone Lookup** takes phone numbers and returns, for each number, one **verdict row** (valid or not, country, region, carrier, line type, time zones, SMS capability, risk level) with the risky line type (VoIP, premium-rate, toll-free and so on) in its `riskLevel` and `riskFlags` fields, and one **signal row** for each community warning sign it finds: a **community spam rating** and every **reported category** such as Telemarketer or Scam call. Paste a list, get JSON, CSV or Excel, and call it from the Apify API, schedules and integrations. No API keys.

#### Free vs paid

| | Free plan | Paid plan |
|---|---|---|
| Numbers per run | 3 | up to 200 |
| Rows per run | up to 8 rows in total | no limit |
| Signal rows | one of each kind (community rating, reported category) plus a count of what stayed locked | all of them |
| Locked-count summary | last row `free-plan-preview` shows shown / locked / estimated cost | not needed |
| Price | 1.5 × list price | list price |

A free run ends SUCCEEDED with the preview row and a status message such as "Free preview: 3 number(s) shown, 5 more row(s) locked. Upgrade to a paid Apify plan for all of them. (~$0.41 on a paid plan)". The preview row states what the whole input would cost on a paid plan at list price.

### Why use it?

- **Clean a call or SMS list**: drop invalid, VoIP and premium-rate numbers before you dial or text.
- **Fraud and trust checks**: see whether a number has community reports as Scam call or Telemarketer, with vote counts.
- **Lead and OSINT research**: one run turns a column of numbers into carrier, region and risk columns.

### How to use Reverse Phone Lookup

1. Open the Input tab and paste numbers in international format, e.g. `+14155551234`, `+821012345678`.
2. Keep "I acknowledge the legal disclaimer" checked.
3. Click Start. Open the Output tab, or call the dataset API.

### Input

| Field | What it does |
|---|---|
| `phoneNumbers` | Numbers to look up, up to 200 per run (free plan: 3) |
| `number` | One number, if you prefer a single field |
| `defaultRegion` | Two-letter country code for numbers written without a country code |
| `disclaimerAck` | Required acknowledgment of lawful use |

### Output

Three row types carry a charge. Notice and `free-plan-preview` rows are messages and are never charged.

```json
{
  "rowType": "reputation-checked",
  "input": "+14155551234",
  "e164": "+14155551234",
  "source": "shouldianswer-us",
  "result": "no-community-reports"
}
{
  "rowType": "number-checked",
  "input": "+18005551212",
  "e164": "+18005551212",
  "valid": true,
  "countryName": "United States",
  "numberTypeLabel": "toll-free",
  "riskLevel": "low",
  "headline": "+1 800 555 1212 — valid US toll-free — CAUTION: 98 negative community reports",
  "layers": { "profile": "done", "reputation": "checked", "telegram": "off-needs-customer-session", "whatsapp": "off-needs-customer-session" }
}
{
  "rowType": "signal-found",
  "e164": "+18005551212",
  "signalType": "report-category",
  "source": "shouldianswer-us",
  "signal": "Telemarketer",
  "severity": "medium",
  "count": 59,
  "detail": "Reported 59 time(s) as \"Telemarketer\"."
}
```

#### What each layer covers

| Layer | Coverage |
|---|---|
| Numbering plan (profile) | Every country |
| Community reports | United States and South Korea numbers. Other countries show `reputation: "not-covered"`, which means *not looked up*, not *clean* |
| `reputation: "unreadable"` | The source could not be read for this number; no `reputation-checked` or signal rows are written and nothing is charged for them |
| Telegram and WhatsApp | **Off.** They need an account session that this Actor does not have. The row says `off-needs-customer-session` |

`deepLinks` gives you `wa.me` and `t.me` links for convenience; opening them tells you nothing about whether the number is registered, so they are not signals and are not charged.

### Pricing

| Event | When | Price (paid plan, list) |
|---|---|---|
| `run-started` | Once per run, including a run whose input is rejected | $0.01 |
| `number-checked` | Each number answered with a verdict row (invalid numbers too — "invalid" is an answer) | $0.02 |
| `reputation-checked` | Each US or Korean number whose community-report page was read to the end, with or without reports ("no reports" is an answer) | $0.02 |
| `signal-found` | Each signal row (community rating, reported category) | $0.03 |

Prices above are the list price a paid Apify plan pays; the Free plan pays 1.5 × list (for example $0.03 per number checked). A US or Korean number with no reports costs $0.04 ($0.02 verdict + $0.02 report lookup) plus its share of the start fee; a number from another country costs $0.02; a US number with a rating and three reported categories costs $0.16 ($0.02 verdict + $0.02 report lookup + 4 × $0.03 signals) plus its share of the start fee. Set a maximum cost per run in the Apify run options and the run stops at it and still ends SUCCEEDED. If the platform's price list cannot be read, the start fee is not charged and the notice says it could not be confirmed.

### Tips

- Use E.164 (`+` then country code) for the cleanest results.
- The reputation source is polled one request at a time with a 1.5 s gap, so a 200-number US list takes several minutes.
- Looking for the PhoneInfoga engine and its footprint search links? See [phoneinfoga-osint](https://apify.com/ntriqpro/phoneinfoga-osint). To check a whole list for format only, see [phone-number-validator-bulk](https://apify.com/ntriqpro/phone-number-validator-bulk).

### FAQ, disclaimer and support

Public information only: numbering-plan data from libphonenumber (Apache-2.0) and public community reports from Should I Answer. This Actor is not affiliated with, endorsed by or sponsored by any source named in its rows. You are responsible for lawful use and privacy-law compliance, and for how you use the results. Community reports are opinions of other callers and can be wrong. This Actor stores no personal data. Questions or a number that reads wrong: open the Issues tab.

# Actor input Schema

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

Phone numbers to look up, in international format with the country code, e.g. +14155551234, +821012345678. Up to 200 numbers per run. Free plan: the first 3 numbers and at most 8 rows, one signal row of each kind (rating, category), with the rest counted as locked (paid plans receive everything).

## `number` (type: `string`):

A single number, as an alternative to the list above.

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

Optional two-letter country code used to read numbers written without a country code, e.g. US, KR, GB.

## `disclaimerAck` (type: `boolean`):

Required. You confirm lawful use only (fraud prevention, authorized security research, journalism, numbers you are authorized to investigate), no harassment or stalking, and that you are responsible for privacy-law compliance. Community reports covered: US and Korean numbers; other countries get the numbering-plan answer only.

## Actor input object example

```json
{
  "phoneNumbers": [
    "+18005551212",
    "+12025550123",
    "+14155551234",
    "+821012345678"
  ],
  "disclaimerAck": true
}
```

# 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 = {
    "phoneNumbers": [
        "+18005551212",
        "+12025550123",
        "+14155551234",
        "+821012345678"
    ],
    "defaultRegion": "",
    "disclaimerAck": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("ntriqpro/reverse-phone-lookup").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 = {
    "phoneNumbers": [
        "+18005551212",
        "+12025550123",
        "+14155551234",
        "+821012345678",
    ],
    "defaultRegion": "",
    "disclaimerAck": True,
}

# Run the Actor and wait for it to finish
run = client.actor("ntriqpro/reverse-phone-lookup").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 '{
  "phoneNumbers": [
    "+18005551212",
    "+12025550123",
    "+14155551234",
    "+821012345678"
  ],
  "defaultRegion": "",
  "disclaimerAck": true
}' |
apify call ntriqpro/reverse-phone-lookup --silent --output-dataset

```

## MCP server setup

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

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/Am3SgbrZDHbopISec/builds/oKwgstWpSq0qJRuUf/openapi.json