WhatsApp Number Lookup API: Validate & Enrich Phone Numbers

Q: How do I check whether a number is a WhatsApp Business account?

Call get-biz-profile with the userHash; a personal number returns isBusiness=false. For many numbers at once, batch-check-10 reports business status alongside registration for each number.

Published August 23, 2026 · UpdatedOctober 9, 2026

A WhatsApp number lookup API turns a raw phone number into structured data. Is this number on WhatsApp? If so, what does its public profile show: a photo, an "about" line, business details, an online signal? Instead of maintaining fragile automations around the apps, you call an HTTP endpoint and get JSON back.

This guide explains the operations in the WhatsApp Number Validation and Profile Lookup project, the two-step userHash flow that ties them together, and how to use them from Python without wasting credits.

What the API can do

The project groups its operations around one goal, learning about a number:

Registration checks: check-exist-by-phone, check-exist-by-cc-phone and check-active tell you whether a number has an active WhatsApp account.
Profile data: get-avatar and get-about return the display photo and the About text.
Presence: get-presence reports an online or last-seen signal, within the limits of the person's privacy settings.
Business profile: get-biz-profile returns business details for WhatsApp Business accounts.
Bulk validation: batch-check-10 checks up to 10 numbers in one request.
Sparse extras: get-device-name, get-email and get-wa-old-device-name are only available when the check says they exist.

Step 1: Get an API key

Sign up, open your Dashboard and copy an active API key. New accounts get free credits, so you can experiment immediately.

Step 2: Validate a number

check-exist-by-phone is a lightweight existence check for a single number. It is cheaper than a full profile lookup. Pass the full international number; the API accepts it with or without a +, with spaces or dashes, or with a 00 prefix, and parses the country code for you.

curl "https://api.opendata-api.com/api/project/whatsapp/check-exist-by-phone?key=YOUR_API_KEY&phoneNumber=15551234567"

The result field isExist is three-state: true, false, or null. A null means the answer was indeterminate, and the right reaction is to retry after a short backoff, not to mark the number as unregistered. When isExist is true, the response also contains:

userHash: an identifier that authorizes the heavier lookups below. It is valid for 24 hours.
hasExtra: which enrichment fields exist for this number. Avatar and about are always available for a registered number; deviceName, email and waOldDeviceName appear only when known.

If you already store the country code and the national number separately, check-exist-by-cc-phone takes them as cc (the dial prefix without +, 1 to 4 digits) and phone (the national number, 6 to 15 digits, no leading zero). If you only need a quick yes or no and do not plan to enrich, check-active returns a direct active flag for a full international number without a userHash.

Step 3: Enrich with profile data

Pass the userHash from the previous step. The number itself is resolved on the server, so these operations accept no phone parameter, and an invalid or expired hash is rejected.

curl "https://api.opendata-api.com/api/project/whatsapp/get-avatar?key=YOUR_API_KEY&userHash=USER_HASH"
curl "https://api.opendata-api.com/api/project/whatsapp/get-about?key=YOUR_API_KEY&userHash=USER_HASH"
curl "https://api.opendata-api.com/api/project/whatsapp/get-biz-profile?key=YOUR_API_KEY&userHash=USER_HASH"

What each one returns, and what an empty result means:

get-avatar: when pictureSet=true you get a temporary photo URL and a picture version id that changes when the photo changes. pictureSet=false means the user has no photo or hides it, and reason explains why.
get-about: the About text and the profile-picture version id. An empty about means no status text or a hidden one.
get-biz-profile: business name, verified level, description, address, email, website and member-since info. A personal number returns isBusiness=false.
get-presence: online state or last seen. If the person is not your contact and their privacy is not set to everyone, presence is not delivered and visible=false. That is a real result and cannot be bypassed. A single call can take up to about 17 seconds, so run it only where you need it.

Read what you can and cannot get from a WhatsApp profile before you build a feature that depends on these fields.

A Python example that does not waste credits

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://api.opendata-api.com/api/project/whatsapp"


def get(operation, **params):
    params["key"] = API_KEY
    resp = requests.get(f"{BASE}/{operation}", params=params, timeout=60)
    resp.raise_for_status()
    body = resp.json()
    # A reply can be wrapped more than once as {"code": ..., "data": {...}}
    while isinstance(body, dict) and "code" in body and isinstance(body.get("data"), (dict, list)):
        body = body["data"]
    return body


def whatsapp_profile(number):
    found = get("check-exist-by-phone", phoneNumber=number)
    exists = found.get("isExist")
    if exists is None:
        return {"number": number, "status": "retry"}
    if not exists:
        return {"number": number, "status": "not_on_whatsapp"}

    user_hash = found.get("userHash")
    if not user_hash:
        raise RuntimeError(f"no userHash in reply: {found}")
    avatar = get("get-avatar", userHash=user_hash)
    about = get("get-about", userHash=user_hash)
    business = get("get-biz-profile", userHash=user_hash)
    return {
        "number": number,
        "status": "registered",
        "has_photo": bool(avatar.get("pictureSet")),
        "about": about.get("about") or None,
        "is_business": bool(business.get("isBusiness")),
        "extras": found.get("hasExtra"),
    }


print(whatsapp_profile("15551234567"))

Only registered numbers reach the profile calls, and a number whose check came back indeterminate is flagged for a retry rather than dropped.

Which operation should I use?

Goal	Operation
Validate one number in a sign-up form	`check-exist-by-phone` or `check-active`
Validate a small batch at once	`batch-check-10`
Clean a large list	batches of 10, see bulk verification
Show a photo or About line	`check-exist-by-phone`, then `get-avatar` / `get-about`
Detect business accounts	`get-biz-profile`, or `batch-check-10`, which also reports business status

If you are still choosing between messengers, WhatsApp vs Telegram lookup compares what each one returns. The step-by-step basics for a single number are in how to check if a number is on WhatsApp.

Where it is used

Lead qualification: verify and enrich inbound leads before routing them to sales.
List hygiene: keep CRM contacts limited to WhatsApp-reachable numbers.
Onboarding: confirm a user can receive WhatsApp messages before switching channels.
Research and enrichment: attach public profile data to known numbers at scale.

Best practices

Validate before you enrich. Skip profile calls for numbers that fail the registration check.
Treat null as retry. Indeterminate results are transient.
Cache the check result. Store isExist, userHash and a timestamp, and reuse the hash for 24 hours instead of checking again.
Do not promise fields. Photos, About text and presence depend on each person's privacy settings.
Stay compliant. Process only numbers you have a lawful basis to use, and respect WhatsApp's terms.

FAQ

What is a userHash and why do I need it? It is an identifier returned by the registration check for a registered number. The profile operations (avatar, about, business profile, presence and the extras) require it to authorize the heavier lookup, and it is valid for 24 hours.

What does a null isExist mean? The answer was indeterminate, for example because of a transient failure. Retry after a short backoff. Do not treat it as "not on WhatsApp".

How do I check whether a number is a WhatsApp Business account? Call get-biz-profile with the userHash; a personal number returns isBusiness=false. For many numbers at once, batch-check-10 reports business status alongside registration for each number.

Do I need a WhatsApp account of my own to use these lookups? No. These operations take only your API key plus the number or the userHash; you do not create a session or link an account. Sending messages is a separate flow that does use a session.

Why is the About text empty? An empty value means the person has no status text or hides it. It is a normal result, not an error.

Get started

Try it in the browser on the WhatsApp Number Validation page, read the check-exist-by-phone and get-avatar references, and review pricing when you are ready to scale beyond the free credits.