# Phone Number OSINT Scanner (`automation-lab/phone-number-osint-scanner`) Actor

Batch-scan authorized phone numbers for normalized country, region, carrier, line type, time zones, and public web-footprint investigation links.

- **URL**: https://apify.com/automation-lab/phone-number-osint-scanner.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Lead generation, Developer tools, Automation
- **Stats:** 2 total users, 0 monthly users, 86.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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/platform/actors/running/actors-in-store#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

## Phone Number OSINT Scanner

Batch-scan phone numbers you are authorized to investigate and receive normalized numbering-plan metadata plus categorized public web-footprint search queries.

This **phone number OSINT** Actor is designed for fraud review, security triage, trust-and-safety operations, and repeatable data enrichment. It uses open-source, offline phone metadata and PhoneInfoga-style search-query generation. It does not use paid lookup APIs, private subscriber databases, or credentialed sources.

> Public search links are investigation starting points. They are not proof that a page, account, or person belongs to the phone subscriber.

### What does Phone Number OSINT Scanner do?

For every unique input number, the Actor can:

- parse international and national phone formats;
- normalize the number to E.164;
- check whether its structure is possible and valid;
- identify the numbering-plan country or territory;
- return an approximate region when offline metadata supports it;
- classify the line as fixed, mobile, VoIP, toll-free, or another known type;
- return original carrier metadata when available;
- list associated time zones;
- generate focused public search queries for social, reputation, disposable-number, general-web, and document research;
- save one consistent JSON record per scanned number.

All metadata lookups run locally inside the Actor container. No phone number is sent to a paid validation or identity service.

### Who is this phone number lookup for?

#### Fraud and risk analysts

Normalize numbers from authorized cases before reviewing public reputation reports, disposable-number directories, or document references.

#### Trust and safety teams

Turn inconsistent international input into a standard dataset that can be joined with internal case data.

#### Security researchers

Generate repeatable, categorized search expressions without manually formatting every national and international number variant.

#### Data operations teams

Process up to 1,000 input entries per run, deduplicate them, and export typed records to spreadsheets, databases, or downstream Actors.

### Why use this Actor?

- **Batch-first input:** scan one authorized number or an international list.
- **No paid lookup key:** the core metadata route is local and open source.
- **Honest nulls:** carrier and locality fields stay null when numbering-plan data cannot support an answer.
- **Typed invalid results:** one malformed number does not stop the rest of a valid batch.
- **Focused footprints:** select only the public query categories relevant to the investigation.
- **Automation-ready output:** each unique number produces one stable dataset item.
- **Privacy boundary:** no private subscriber identity, call records, message content, live location, or ownership claim.

### What phone data is returned?

| Field | Meaning |
| --- | --- |
| `input` | Original supplied phone string |
| `isValid` | Validity against the current numbering plan |
| `isPossible` | Whether length and structure are possible |
| `error` | Per-number parsing or validity explanation |
| `e164` | Normalized E.164 number |
| `internationalFormat` | Human-readable international format |
| `nationalFormat` | Human-readable national format |
| `nationalNumber` | National significant number |
| `countryCode` | ISO alpha-2 country or territory code |
| `countryName` | English country or territory name |
| `callingCode` | International calling code |
| `region` | Approximate numbering-plan locality or country fallback |
| `carrier` | Original range carrier when available |
| `lineType` | Fixed, mobile, VoIP, toll-free, or another known class |
| `timeZones` | Numbering-plan time zones |
| `metadataSource` | Local metadata route used |
| `webFootprintQueries` | Categorized public search expressions and URLs |
| `footprintQueryCount` | Number of generated queries |
| `scannedAt` | ISO timestamp for the scan |

### Public web-footprint categories

The Actor can generate the following query families:

- `general` — exact-number variants across the public web;
- `social_media` — focused queries for Facebook, LinkedIn, Instagram, and X;
- `reputation` — phone-reporting sites and general fraud-report language;
- `disposable_number` — public receive-SMS directory queries;
- `documents` — public PDF, Word, spreadsheet, and CSV references.

The Actor generates URLs only. It does not claim that Google will return a result, scrape result pages, bypass access controls, or establish subscriber identity.

### How to run a phone number OSINT scan

1. Open the Actor in Apify Console.
2. Add one or more phone numbers under **Phone numbers**.
3. Prefer E.164 input such as `+1 202-456-1111`.
4. For national-format input, set a two-letter `defaultCountry` such as `US`, `GB`, or `DE`.
5. Confirm **I confirm authorized use**.
6. Keep all footprint categories, or select only the categories needed for the case.
7. Set **Maximum phone scans** to control the number of unique records.
8. Click **Start**.
9. Open the Dataset tab to review or export results.

### Input parameters

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `phoneNumbers` | string array | required | One to 1,000 phone-number strings |
| `authorizedUse` | boolean | `false` | Required confirmation that every number may be investigated |
| `defaultCountry` | string | none | ISO alpha-2 fallback for national-format numbers |
| `includeFootprintQueries` | boolean | `true` | Generate categorized Google investigation links |
| `footprintCategories` | string array | all categories | Limit generated query families |
| `maxItems` | integer | `100` | Process at most this many unique numbers |

#### Example input

```json
{
  "phoneNumbers": [
    "+1 202-456-1111",
    "+44 20 7219 3000",
    "+49 30 18 17 0"
  ],
  "authorizedUse": true,
  "includeFootprintQueries": true,
  "footprintCategories": [
    "general",
    "reputation",
    "documents"
  ],
  "maxItems": 3
}
```

### Phone number OSINT output example

The following abbreviated record reflects current Actor behavior for a publicly listed organization number:

```json
{
  "input": "+1 202-456-1111",
  "isValid": true,
  "isPossible": true,
  "error": null,
  "e164": "+12024561111",
  "internationalFormat": "+1 202 456 1111",
  "nationalFormat": "(202) 456-1111",
  "nationalNumber": "2024561111",
  "countryCode": "US",
  "countryName": "United States",
  "callingCode": "+1",
  "region": "Washington D.C.",
  "carrier": null,
  "lineType": "fixed_line_or_mobile",
  "timeZones": ["America/New_York"],
  "metadataSource": "libphonenumber offline metadata",
  "webFootprintQueries": [
    {
      "category": "reputation",
      "source": "Tellows",
      "query": "site:tellows.com (\"+12024561111\" OR \"+1 202 456 1111\" OR \"(202) 456-1111\")",
      "url": "https://www.google.com/search?q=site%3Atellows.com..."
    }
  ],
  "footprintQueryCount": 11,
  "scannedAt": "2026-08-01T12:00:00.000Z"
}
```

### How much does it cost to scan phone numbers?

The Actor uses pay-per-event pricing:

- **$0.00005 per run** for the `start` event;
- **$0.024 per phone scanned at the BRONZE tier**;
- lower per-scan prices apply at higher Apify pricing tiers.

Approximate BRONZE-tier examples:

| Unique phone scans | Approximate charge (USD) |
| ---: | ---: |
| 1 | 0.02405 |
| 10 | 0.24005 |
| 100 | 2.40005 |

Duplicates removed before processing do not create additional scan records. Invalid-but-processed phone strings do produce a typed dataset item and count as a scan. Your Apify subscription tier and maximum total charge setting remain the final billing controls.

### Batch fraud-review workflow

A practical authorized workflow is:

1. Export phone numbers from an internal case-management system.
2. Remove numbers outside the approved investigation scope.
3. Run this Actor with reputation and disposable-number categories.
4. Join results back to the case table using `e164`.
5. Route invalid numbers to data-quality review.
6. Review public search links manually or through an approved downstream process.
7. Record human conclusions separately from Actor-generated metadata.

This separation prevents generated queries from being mistaken for verified findings.

### Scheduling and change comparison

You can schedule the Actor to re-normalize an authorized list when numbering-plan metadata updates. Use Apify Schedules and compare datasets by `e164`.

The Actor does not monitor search results or claim that a public footprint changed. A recurring run regenerates current metadata and query URLs; downstream systems own any result-page retrieval and change detection.

### Export and integrations

Dataset records can be exported as JSON, CSV, Excel, XML, or RSS through Apify storage APIs.

Common integrations include:

- Google Sheets for analyst review;
- Make or Zapier for case-routing automation;
- webhooks for completed-run notifications;
- Python or JavaScript ETL pipelines;
- database enrichment keyed by normalized E.164 number;
- LLM workflows that summarize already-authorized, human-reviewed findings.

Do not send unreviewed search results to automated enforcement decisions.

### Run with the Apify API using cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~phone-number-osint-scanner/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["+1 202-456-1111"],
    "authorizedUse": true,
    "footprintCategories": ["reputation"],
    "maxItems": 1
  }'
```

Never commit `APIFY_TOKEN` to source control. Prefer an Authorization header or a secrets manager in production.

### Run with JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor('automation-lab/phone-number-osint-scanner').call({
  phoneNumbers: ['+1 202-456-1111'],
  authorizedUse: true,
  footprintCategories: ['general', 'reputation'],
  maxItems: 1,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Run with Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/phone-number-osint-scanner').call(run_input={
    'phoneNumbers': ['+44 20 7219 3000'],
    'authorizedUse': True,
    'footprintCategories': ['reputation', 'documents'],
    'maxItems': 1,
})

items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Use with Apify MCP

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/phone-number-osint-scanner"
```

#### Claude Desktop

Add this server entry to the Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/phone-number-osint-scanner"
    }
  }
}
```

#### Cursor

In Cursor MCP settings, add an HTTP server named `apify` with this URL:

```text
https://mcp.apify.com?tools=automation-lab/phone-number-osint-scanner
```

#### VS Code

In a VS Code client with MCP support, add the same HTTP URL as the `apify` server in the workspace MCP configuration.

Example prompts:

- “Normalize these authorized support numbers and return country, region, line type, and time zone.”
- “Generate only reputation and disposable-number investigation queries for this approved fraud case list.”
- “Separate invalid numbers from valid E.164 records in this Actor dataset.”

### Accuracy and limitations

- Validity means numbering-plan validity, not that a number is active or reachable.
- Carrier metadata describes original number-range allocation and may be stale after number portability.
- Region data is approximate and is not live device location.
- A country calling code can cover several territories.
- Some valid numbers have no carrier, line type, or locality metadata.
- Generated search links can return no results, unrelated results, CAPTCHA pages, or results that change over time.
- The Actor does not access Numverify, Google Custom Search, OVH account data, private subscriber databases, call records, or messaging services.
- The Actor does not identify a private person.

### Invalid input and failure behavior

A syntactically bad phone string produces a dataset item with:

- `isValid: false`;
- `isPossible: false`;
- a clear `error` message;
- null normalized metadata;
- no footprint queries.

The run fails before charging when:

- `phoneNumbers` is missing or empty;
- an entry is not a string;
- more than 1,000 entries are supplied;
- `authorizedUse` is not `true`;
- `defaultCountry` is unsupported;
- a footprint category is unsupported.

### Responsible and legal use

Only scan phone numbers you own or are authorized to investigate. Follow applicable privacy, data-protection, employment, consumer-protection, and anti-harassment laws.

Do not use this Actor to:

- stalk, harass, intimidate, or discriminate against a person;
- infer or publish private subscriber identity;
- make eligibility, credit, employment, housing, insurance, or law-enforcement decisions without lawful process and human review;
- bypass access controls, CAPTCHAs, or source terms;
- contact a number without a lawful basis;
- treat generated queries as verified evidence.

You are responsible for your input, downstream searches, retention policy, and conclusions.

### Troubleshooting

#### Why is `carrier` null?

Fixed-line ranges often have no carrier mapping. Mobile number portability can also make original allocation data incomplete or stale. Null is intentional when the offline dataset cannot support a reliable value.

#### Why is a valid-looking national number invalid?

Set `defaultCountry` to the correct two-letter code, or provide the number in E.164 format beginning with `+` and its calling code.

#### Why are there no web-footprint queries?

Queries are generated only for valid numbers when `includeFootprintQueries` is true. Check the selected `footprintCategories` and the per-number `error` field.

#### Does the Actor open every search result?

No. It generates categorized public investigation URLs. It does not scrape Google or target pages.

### FAQ

#### Does this reveal the phone owner?

No. The Actor returns numbering-plan metadata and research links, not private subscriber identity.

#### Can I scan national-format phone numbers?

Yes. Supply `defaultCountry`, for example `US`, `GB`, or `DE`.

#### Are duplicate numbers charged twice?

Exact duplicate input strings are deduplicated before scanning. Equivalent numbers written in different formats are separate input strings and can produce separate records; normalize upstream if this matters.

#### Can I disable footprint queries?

Yes. Set `includeFootprintQueries` to `false` for metadata-only processing.

#### Is a proxy required?

No. The Actor's metadata and query generation are local and require no proxy.

#### Can I use this in a scheduled workflow?

Yes, for approved recurring normalization or data-quality checks. The Actor itself does not monitor search-result changes.

### Related automation-lab Actors

- [Phone Number Validator](https://apify.com/automation-lab/phone-number-validator) — use when you need lightweight validation and formatting without OSINT query generation.
- [Website Contact Finder](https://apify.com/automation-lab/website-contact-finder) — extract publicly listed contact details from authorized websites before normalizing phone records.

### Open-source route and attribution

The implementation follows the local metadata and public-query route family popularized by [PhoneInfoga](https://github.com/sundowndev/phoneinfoga). PhoneInfoga is GPL-3.0 licensed. This Actor uses separately packaged open-source libphonenumber metadata components and does not bundle the PhoneInfoga binary, paid scanners, or credentialed services.

### Support

For reproducible support, include:

- a redacted input that preserves formatting;
- the run ID;
- the expected country or numbering plan;
- the output field that appears incorrect;
- whether the issue affects one number or an entire batch.

Never post a private individual's phone number in a public support thread.

# Actor input Schema

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

International numbers in E.164 format are recommended. National-format numbers require defaultCountry. Duplicates are scanned once.

## `authorizedUse` (type: `boolean`):

Confirm that you are authorized to investigate every supplied number and will comply with privacy, data-protection, and platform rules.

## `defaultCountry` (type: `string`):

Optional ISO 3166-1 alpha-2 country code used only for numbers without an international prefix, such as US, GB, or DE.

## `includeFootprintQueries` (type: `boolean`):

Generate categorized Google investigation links. Links are research starting points, not evidence that a result belongs to a subscriber.

## `footprintCategories` (type: `array`):

Optional categories to include. Leave unchanged to generate all supported categories.

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

Maximum number of unique phone numbers to process from the input list.

## Actor input object example

```json
{
  "phoneNumbers": [
    "+1 202-456-1111",
    "+44 20 7219 3000",
    "+49 30 18 17 0"
  ],
  "authorizedUse": true,
  "includeFootprintQueries": true,
  "footprintCategories": [
    "general",
    "social_media",
    "reputation",
    "disposable_number",
    "documents"
  ],
  "maxItems": 20
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset containing one typed result for each unique phone number scanned.

# 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": [
        "+1 202-456-1111",
        "+44 20 7219 3000",
        "+49 30 18 17 0"
    ],
    "authorizedUse": true,
    "includeFootprintQueries": true,
    "footprintCategories": [
        "general",
        "social_media",
        "reputation",
        "disposable_number",
        "documents"
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/phone-number-osint-scanner").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": [
        "+1 202-456-1111",
        "+44 20 7219 3000",
        "+49 30 18 17 0",
    ],
    "authorizedUse": True,
    "includeFootprintQueries": True,
    "footprintCategories": [
        "general",
        "social_media",
        "reputation",
        "disposable_number",
        "documents",
    ],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/phone-number-osint-scanner").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": [
    "+1 202-456-1111",
    "+44 20 7219 3000",
    "+49 30 18 17 0"
  ],
  "authorizedUse": true,
  "includeFootprintQueries": true,
  "footprintCategories": [
    "general",
    "social_media",
    "reputation",
    "disposable_number",
    "documents"
  ],
  "maxItems": 20
}' |
apify call automation-lab/phone-number-osint-scanner --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/phone-number-osint-scanner"
        }
    }
}

```

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/k51bOhEhPtSPffJyE/builds/2zjwxvBR5W4arRb96/openapi.json