# 🔎 WhatsApp Number Lookup — Bulk Verify, Photo, Business Info (`apivault_labs/whatsapp-data-lookup`) Actor

Bulk WhatsApp number lookup & verification: is the number on WhatsApp, profile photo (permanent link), about text, business details (category, email, website, address, hours), number intelligence & lead score. CSV upload, 7-day cache. No login, no keys.

- **URL**: https://apify.com/apivault\_labs/whatsapp-data-lookup.md
- **Developed by:** [Apivault Labs](https://apify.com/apivault_labs) (community)
- **Categories:** Lead generation
- **Stats:** 10 total users, 9 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 profile enricheds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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?

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

## 🔎 WhatsApp Number Lookup & Verification — Bulk Check, Profile Photo, Business Data

Turn a raw phone list into **ranked, enriched WhatsApp leads**. Bulk-check
whether numbers are registered on WhatsApp and get back a full profile per
number — ready for outreach, CRM cleaning and lead generation.

> **Just need true/false validation?** Use the lighter **WhatsApp Number
> Validator** ($0.80–1.5/1K). This actor is for teams who need *enrichment* —
> profile photos, business email & website, about text and lead scoring — to
> prioritise outreach.

### What you get per number

| Field | Description | Needs a token? |
|---|---|---|
| `onWhatsApp` | Is the number on WhatsApp right now (true/false) | No |
| `profilePhotoUrl` / `hasProfilePhoto` | Public profile picture — rehosted to permanent storage (never expires) | No |
| `profilePhotoStatus` | Why no photo: `ok` / `private` (locked by privacy settings) / `none` (no photo set) | No |
| `displayName` | Public profile / business display name | No |
| `isBusiness` | Business-account flag | No |
| `valid`, `e164`, `international`, `national` | Validity + all phone formats | No |
| `country`, `regionCode`, `carrier`, `lineType` | Number intelligence | No |
| `timezones`, `localTimeNow`, `bestTimeToMessage` | When to reach them | No |
| `leadScore` (0–100), `leadQuality` | Ranked outreach priority | No |
| `about` | About / status text | No |
| `businessName`, `businessCategory`, `businessEmail`, `businessWebsite`, `businessAddress`, `businessHours` | Extended business details | No |
| `verifiedName` | Verified business name | No |

Everything works with **no setup and no tokens**: registration, photo, about
text and full business details are all built in.

### Why enrichment beats validation

A bare `valid: true` is useless for outreach. *"On WhatsApp + has a profile
photo + business account named Acme Plumbing"* is a **hot lead**. Each extra
data point is a reason to message this contact first — that's what agencies pay
for.

### Input

Paste numbers into **Phone numbers** (one per line), **paste a list / CSV
column** into the text box, or **upload a CSV/TXT file**. Include the country
code with a leading `+` (e.g. `+14155552671`), or set a **Default country**
for local-format numbers.

### Result caching (cheaper repeats)

Results are cached for **7 days** in your own key-value store. Re-checking the
same number within a week returns instantly and is billed via the cheaper
`result-cached` event — handy for re-validating the same lists on a schedule.

```json
{
  "phoneNumbers": ["+14155238886", "+442071838750"],
  "defaultCountry": "US",
  "businessEnrichment": true
}
```

### Output

```json
{
  "input": "+14155238886",
  "valid": true,
  "e164": "+14155238886",
  "country": "United States",
  "carrier": "",
  "lineType": "fixed-or-mobile",
  "onWhatsApp": true,
  "displayName": "Acme Plumbing",
  "profilePhotoUrl": "https://api.apify.com/v2/key-value-stores/.../photo-14155238886.jpg",
  "hasProfilePhoto": true,
  "about": "Available",
  "isBusiness": true,
  "businessName": "Acme",
  "leadScore": 88,
  "leadQuality": "hot",
  "bestTimeToMessage": "now",
  "localTimezone": "America/Los_Angeles"
}
```

Use the **Ranked leads** dataset view to sort by `leadScore`, or export
CSV-friendly columns with `exportFormat: "csv"`.

Every checked number is returned — each row carries its own
`valid` / `onWhatsApp` / `whatsappStatus` flags, so you filter the results on
your side (e.g. keep only `registered`).

### Honest limits

- **Online / last-seen is not available.** WhatsApp hides presence from
  non-contacts (even the official API does not expose last-seen to third
  parties), so we don't claim it. What *is* reliable — registration, profile
  photo, about text and business details — is what this actor returns.
- Profile photo and about text appear only when the user made them public —
  `profilePhotoStatus` tells you exactly which case it was.

### Notes

- No customer login, QR scan, or API key is required. Bulk processing is built in.
- Every valid number is live-checked — including landlines, since WhatsApp
  Business accounts can sit on fixed lines.

# Actor input Schema

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

Phone numbers to look up (one per line). Include the country code with a leading + when possible, e.g. +14155552671. Numbers without a + are parsed using the Default country below.

## `numbersText` (type: `string`):

Optional. Paste many numbers at once (one per line, or comma/semicolon separated — e.g. a copied spreadsheet column). Merged with the list above and de-duplicated.

## `fileUrl` (type: `string`):

Optional. Upload a .csv or .txt file — phone-looking values are extracted automatically from any column layout (for Excel, export to CSV first). Merged with the fields above and de-duplicated.

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

ISO 3166 alpha-2 region code (US, GB, BR, IN, DE, ...) used to interpret numbers that don't start with +. Leave empty to require + on every number.

## `businessEnrichment` (type: `boolean`):

Fetch about (status) text, business-account flag, business name, category, email, website, address, hours and verified name for registered numbers. No token or setup needed — built in.

## `onlyValid` (type: `boolean`):

Deprecated, no effect: every checked number is returned — each row carries valid / onWhatsApp flags, so filter the results yourself. Every delivered row is billed.

## `onlyWhatsappRegistered` (type: `boolean`):

Deprecated, no effect: every checked number is returned — each row carries valid / onWhatsApp flags, so filter the results yourself. Every delivered row is billed.

## `concurrency` (type: `integer`):

How many lookups to run in parallel. Higher = faster for large lists.

## `timeoutSeconds` (type: `integer`):

Per-request timeout for the live check and enrichment.

## `exportFormat` (type: `string`):

default = full JSON. csv = flat CSV-friendly columns. both = JSON + nested \_csv.

## Actor input object example

```json
{
  "phoneNumbers": [
    "+14155238886",
    "+442071838750",
    "+5511991234567",
    "+919876543210"
  ],
  "defaultCountry": "US",
  "businessEnrichment": true,
  "concurrency": 10,
  "timeoutSeconds": 20,
  "exportFormat": "default"
}
```

# Actor output Schema

## `profiles` (type: `string`):

One record per checked number: registration status, profile photo link, about text, business details, number intelligence and lead score.

## `summary` (type: `string`):

Aggregate totals: checked, valid, registered, cache hits, delivered.

## `photos` (type: `string`):

Profile pictures rehosted to permanent storage, one record per number: photo-<digits>.jpg.

# 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": [
        "+14155238886",
        "+442071838750",
        "+5511991234567",
        "+919876543210"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("apivault_labs/whatsapp-data-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": [
        "+14155238886",
        "+442071838750",
        "+5511991234567",
        "+919876543210",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("apivault_labs/whatsapp-data-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": [
    "+14155238886",
    "+442071838750",
    "+5511991234567",
    "+919876543210"
  ]
}' |
apify call apivault_labs/whatsapp-data-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apivault_labs/whatsapp-data-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/vPgMVzqiBbxqsPQDl/builds/4NR8kzcgjQxZQ7dUX/openapi.json