# Phone OSINT Lookup API — Carrier & Public Footprint (`khadinakbar/phone-osint-lookup-api`) Actor

Normalize phone numbers, return country and line metadata, optionally enrich carrier data, and create non-automated public-web footprint search links.

- **URL**: https://apify.com/khadinakbar/phone-osint-lookup-api.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Developer tools, Lead generation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $25.00 / 1,000 phone metadata resolveds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## Phone OSINT Lookup API — Carrier & Public Footprint

Operations teams, support teams, and AI agents can turn exact phone inputs into one structured dataset record per number. Each result provides E.164 formatting, country and line metadata, optional carrier data, public-web search links, source labels, warnings, and collection time for consented phone-data workflows.

### Best fit and focused standalone workflow

This Actor is designed as a focused standalone workflow for teams that already hold authorized phone numbers. It works well for CRM cleanup, telecom routing research, and support-case preparation where the next decision needs a normalized number, numbering-plan metadata, carrier context, and manual public-web search starting points.

For business, profile, review, or location discovery, start with a dedicated source Actor that collects authorized public records, then pass the exact phone field to this Actor for phone metadata. The result remains a focused standalone workflow when a CRM or support queue already supplies the phone field.

### Workflow story

A support-operations analyst starts with a customer phone field, runs this Actor to standardize it to E.164, confirms the country and line type, and checks the carrier source when available. Next, the analyst opens the supplied public-web links for a manual, context-aware review and exports the dataset row back to the authorized support record.

### Input

```json
{
  "phoneNumbers": ["+12025551234", "(202) 555-1234"],
  "defaultCountry": "US",
  "maxLookups": 10,
  "includeCarrierLookup": true,
  "includeFootprintLinks": true
}
```

Use E.164 where possible. Local numbers use `defaultCountry`; duplicate input values are processed once. `maxLookups` accepts 1 through 100 and provides the run's event-charge cap.

### Output

Each dataset row uses stable typed fields:

| Field | Meaning |
| --- | --- |
| `e164` | Normalized E.164 phone value for consistent downstream matching. |
| `countryCode`, `countryName`, `region`, `city` | Numbering-plan geography when supplied by the metadata source. |
| `lineType`, `carrier`, `carrierSource` | Number-plan line category and optional carrier provenance. |
| `footprintSearchUrls` | Manual public-web search starting points; linked pages remain user-reviewed. |
| `sources`, `warnings`, `lookedUpAt` | Provenance, data-quality context, and collection time. |

```json
{
  "inputNumber": "+12025551234",
  "valid": true,
  "possible": true,
  "e164": "+12025551234",
  "international": "+1 202 555 1234",
  "countryCode": "US",
  "countryName": "United States",
  "region": "DC",
  "city": "Washington",
  "lineType": "fixed_or_mobile",
  "carrier": null,
  "carrierSource": null,
  "footprintSearchUrls": {
    "exactNumberWebSearch": "https://www.google.com/search?q=%22%2B12025551234%22",
    "callerReputationSearch": "https://www.google.com/search?q=%22%2B12025551234%22+caller+reputation",
    "businessDirectorySearch": "https://www.google.com/search?q=12025551234+business+directory"
  },
  "footprintScope": "manual_public_web_search_links",
  "sources": ["libphonenumber", "manual_public_web_search_links"],
  "warnings": [],
  "lookedUpAt": "2026-08-30T00:00:00.000Z"
}
```

### Pricing

The Actor uses Pay per event + platform usage. Actor start costs `$0.00005`, and each valid complete phone-metadata record costs `$0.025`; Apify reports platform usage separately. For a 10-phone maximum, event charges are capped at `$0.250` plus platform usage. Open the live Pricing tab for the current Actor pricing and platform-usage details.

### API and agent use

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('khadinakbar/phone-osint-lookup-api').call({
  phoneNumbers: ['+12025551234'],
  includeCarrierLookup: true,
  includeFootprintLinks: true
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

> As an AI agent, normalize these exact authorized phone numbers, return country and line metadata, include carrier provenance when available, and provide manual public-footprint links. Read the output dataset in pages, retain `sources` and `lookedUpAt` as provenance, and report the terminal `OUTPUT.outcome` with the scoped event cost.

`OUTPUT` supplies the terminal outcome and charge counts. `RUN_SUMMARY` supplies input totals, deduplication, provider status, warnings, and final record counts. Read the default dataset in pages for large batches.

### Best results and practical guidance

Provide exact authorized phone values and select the country that matches local-format inputs. Confirm `carrierSource` before making a routing decision, and treat carrier values as point-in-time telecom metadata. Public-footprint links support an authorized human review with the relevant customer, business, or support context.

### Builder's note

I designed this Actor around one reliable record contract: offline number-plan metadata always remains available, optional carrier enrichment is labeled with its provider, and public-footprint links stay manual. My goal was a predictable AI-agent surface that preserves useful telecom context alongside clear source and collection-time fields.

### Responsible use

Submit phone numbers you are authorized to process and use the public-web links in accordance with applicable laws, privacy duties, telecom rules, and site terms. Carrier and numbering-plan signals support context-aware operations decisions.

# Actor input Schema

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

Exact phone numbers to normalize and inspect, for example '+12025551234'. E.164 input is most reliable, while local numbers use Default country. Provide 1 to 100 values per run. This is not a name, email, or free-text person search.

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

Two-letter ISO country used only to parse local-format numbers, for example 'US'. It defaults to 'US' and is ignored for E.164 inputs such as '+442071838750'. Choose the country where an unprefixed number is dialed. This is not a filter on result countries.

## `maxLookups` (type: `integer`):

Caps the number of unique phone values processed in this run, for example 10. It defaults to 10 and accepts 1 through 100. Duplicate values are processed once to avoid duplicate charges. This is not a concurrency setting.

## `includeCarrierLookup` (type: `boolean`):

Requests current carrier enrichment for valid numbers when the owner-managed IPQS provider is configured. It defaults to true; metadata still returns if the provider is missing or unavailable. Carrier data can be stale after number porting and is labeled with its source. This does not return identity, breach, fraud, or account-presence information.

## `includeFootprintLinks` (type: `boolean`):

Adds Google search URLs using the normalized number for manual review of public web results. It defaults to true and does not fetch, scrape, rank, or claim any third-party matches. Turn it off when you need metadata only. These are not reverse-identity lookups.

## Actor input object example

```json
{
  "phoneNumbers": [
    "+12025551234",
    "+442071838750"
  ],
  "defaultCountry": "US",
  "maxLookups": 10,
  "includeCarrierLookup": true,
  "includeFootprintLinks": true
}
```

# Actor output Schema

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

Default dataset: one metadata record per submitted phone value.

## `output` (type: `string`):

Compact machine-readable run outcome.

## `runSummary` (type: `string`):

Detailed counts, provider status, warnings, and charged events.

## `consoleRun` (type: `string`):

Logs and dataset preview in Apify Console.

# 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": [
        "+12025551234",
        "+442071838750"
    ],
    "defaultCountry": "US",
    "maxLookups": 10,
    "includeCarrierLookup": true,
    "includeFootprintLinks": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/phone-osint-lookup-api").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": [
        "+12025551234",
        "+442071838750",
    ],
    "defaultCountry": "US",
    "maxLookups": 10,
    "includeCarrierLookup": True,
    "includeFootprintLinks": True,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/phone-osint-lookup-api").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": [
    "+12025551234",
    "+442071838750"
  ],
  "defaultCountry": "US",
  "maxLookups": 10,
  "includeCarrierLookup": true,
  "includeFootprintLinks": true
}' |
apify call khadinakbar/phone-osint-lookup-api --silent --output-dataset

```

## MCP server setup

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

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/Jm6mUiKR7L3kA9l9k/builds/vwd9ggdaIvKrjlJCo/openapi.json