WhatsApp Number Lookup API: Pay for Check-Exist Before You Enrich

Published August 23, 2026 · UpdatedOctober 16, 2026

Rafael runs seller onboarding for a São Paulo marketplace. Every inbound shop phone is supposed to land in WhatsApp: is it registered, and if so, does the ticket need a photo, an About line, or a business card? Last quarter he wired check-exist-by-phone and then, for every row, fired get-avatar, get-about, get-biz-profile and get-presence in the same loop. Credits vanished on numbers that were never on WhatsApp, on isExist=null rows he treated as hits, and on four profile hops when the agent only needed one.

A WhatsApp number lookup API is a budget problem first. Existence is the cheap hop. Avatar, About, presence and business sit behind a 24-hour userHash, minted only on a real hit. Opening this page or copying a snippet does not send a lookup. Running a command does, and it spends credits.

Sign in, copy an authorized key from the dashboard, and read it from OPENDATA_API_KEY on the server. Curl examples use the YOUR_API_KEY placeholder. The key travels in the query string, so those URLs do not belong in tickets, screenshots or source control.

Do not enrich the misses

Screen the list with a registration check. Do not call a profile operation until isExist is exactly true.

check-exist-by-phone is the cheap classifier: one GET, one full international number, with or without +, spaces, dashes or a 00 prefix. The documented example 15551234567 is a shape — digits and a country code — not a promised live account.

If country code and national number already live in separate columns, check-exist-by-cc-phone takes cc (1 to 4 digits, no +) and phone (6 to 15 digits, no leading zero). If you will never enrich, check-active returns a direct active flag and does not mint a userHash. Paying for a ticket you will throw away is still a spend.

For a file of leads, batch-check-10 checks up to ten numbers and returns exist plus isBusiness for each — no hash required. Use it to split consumers from shops. List-cleaning is in bulk verification; the three-state single-number path is in how to check if a number is on WhatsApp.

isExist is three-state, and that is the first place credits leak:

  • true — registered. This is the only row that may mint a userHash.
  • false — not registered. A clean miss. Store it. Do not retry it as a timeout, and do not call avatar, About, presence or business.
  • null — undetermined. Transient. Queue a backoff retry of the check, not of a profile hop. Never write null as “not on WhatsApp”, and never treat it as permission to enrich.

HTTP status and gateway status are not isExist. A missing key, a validation error or a transport failure is HTTP 4xx/5xx or a gateway code other than 200 — no WhatsApp verdict, so do not write false. HTTP 2xx with gateway code 200 means the check was delivered; only then read isExist. A delivered null is still undetermined, not a crash. Replies wrap as {"code", "data"} (the platform may wrap once more); unwrap until you see isExist.

Python’s truthiness is how Rafael burned the first pile. None and False are both falsy, so if not isExist merges a miss with a retry, and if isExist: walks null into profile calls. Classify with is True / is False / is None.

Mint userHash only on a hit

When isExist is true, the check returns a userHash valid for 24 hours and a hasExtra map. Avatar and About are always listed for a registered account; deviceName, email and waOldDeviceName appear only when known. The hash is bound to the number the server already resolved. Profile operations accept no phone parameter. A missing, unknown or expired hash is rejected without a lookup.

You do not log in a WhatsApp account and you do not invent the ticket. Store isExist, userHash, hasExtra and a checked-at timestamp. Reuse a hit’s hash until that timestamp plus 24 hours. Re-checking inside the window to “refresh” a hash you already hold wastes a credit; calling get-avatar after expiry wastes a round-trip that fails. Clean misses stay cached for the same window so you do not pay to hear false twice.

check-active and batch-check-10 do not hand you this ticket. A photo, About line or full business card still needs check-exist. If the next hop is only “registered, and is it a shop?”, stay on batch-check-10.

The script below is the budget gate. Install requests, export OPENDATA_API_KEY, run it on the server. It unwraps the envelope, classifies the three-state check, caches a hit’s hash for 24 hours, and — only if you pass enrich — spends one profile hop. Default is check-only. The number is a documented shape, not a guaranteed hit.

import os
from datetime import datetime, timedelta, timezone

import requests

BASE = "https://api.opendata-api.com/api/project/whatsapp"
KEY = os.environ["OPENDATA_API_KEY"].strip()
HASH_TTL = timedelta(hours=24)
CACHE = {}  # number -> check record


def call(operation, timeout=30, **params):
    response = requests.get(
        f"{BASE}/{operation}",
        params={"key": KEY, **params},
        timeout=timeout,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP failure: {response.status_code}")
    body = response.json()
    if not isinstance(body, dict) or body.get("code") not in (200, "200"):
        raise RuntimeError("Gateway business failure; inspect redacted diagnostics")
    # 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 check_exist(number):
    cached = CACHE.get(number)
    if cached:
        checked_at = cached["checked_at"]
        if datetime.now(timezone.utc) - checked_at < HASH_TTL:
            return cached
    found = call("check-exist-by-phone", phoneNumber=number)
    exists = found.get("isExist")
    record = {
        "isExist": exists,
        "userHash": found.get("userHash") if exists is True else None,
        "hasExtra": found.get("hasExtra") if exists is True else None,
        "checked_at": datetime.now(timezone.utc),
    }
    if exists is not None:  # cache hits and clean misses; do not cache undetermined
        CACHE[number] = record
    return record


def lookup(number, enrich=None):
    """enrich is one of: avatar, about, biz, presence, or None (check only)."""
    record = check_exist(number)
    exists = record["isExist"]
    if exists is None:
        return {"number": number, "status": "undetermined"}
    if exists is False:
        return {"number": number, "status": "not_on_whatsapp"}
    out = {
        "number": number,
        "status": "registered",
        "hasExtra": record.get("hasExtra"),
    }
    user_hash = record.get("userHash")
    if not user_hash or enrich is None:
        return out
    if enrich == "avatar":
        avatar = call("get-avatar", userHash=user_hash)
        out["pictureSet"] = avatar.get("pictureSet")
        out["reason"] = avatar.get("reason")
    elif enrich == "about":
        about = call("get-about", userHash=user_hash)
        out["about"] = about.get("about") or None
    elif enrich == "biz":
        biz = call("get-biz-profile", userHash=user_hash)
        out["isBusiness"] = biz.get("isBusiness")
    elif enrich == "presence":
        presence = call("get-presence", timeout=60, userHash=user_hash)
        out["visible"] = presence.get("visible")
    else:
        raise ValueError("enrich must be avatar, about, biz, presence, or None")
    return out


if __name__ == "__main__":
    print(lookup("15551234567", enrich=None))

Call lookup(number, enrich=None) across the file first. Persist statuses. Then, for rows that are registered and that a human will see, call again with one enrich value. The in-process CACHE is a sketch; persist the same record next to the contact so a second worker does not mint a second hash.

Avatar, About, presence, business — pick one

Each of these is a separate spend. Pick the field the ticket actually shows. An empty field is a paid answer, not a reason to fire the next operation “just in case”.

  • get-avatar — pictureSet=true gives a temporary photo URL and a version id that changes with the photo. Download the bytes if the ticket must keep a face. pictureSet=false means no photo or a hidden one; reason explains why. Finished.
  • get-about — About text and a picture version id. Empty about means none or hidden. Do not retry until a slogan appears.
  • get-biz-profile — name, verified level, description, address, email, website, member-since. A personal number returns isBusiness=false. If you only needed that boolean, batch-check-10 already had it without a hash.
  • get-presence — online or last-seen, only when privacy allows. Not a contact and last-seen not “everyone” → visible=false. That cannot be bypassed. A call can take ~17 seconds; use it only when the signal is worth the wait and the credit.

Sparse extras (get-device-name, get-email, get-wa-old-device-name) exist only when hasExtra lists them. The email is a masked backup address, not a shop inbox. Skip anything not advertised. Payload shapes live in WhatsApp profile: avatar, About, presence.

Rafael’s fix was one column on the ticket: photo or About or business card, chosen by queue. Support sees a face. Sales sees isBusiness and the verified name. Presence stays off the default path.

What this project is not

This is public-number intelligence, not a WhatsApp client. It does not send messages, read chats, or open a session — that is a different project. You do not need your own WhatsApp account; you need an authorized platform key and a number you have a lawful basis to process.

It is not a promise that a registered number has a photo, an About line, last-seen or a shop card. Privacy hides those fields. Empty is valid. Retrying a clean miss, pictureSet=false, an empty about or visible=false until it becomes a profile only spends credits.

It is not a reason to enrich every CRM row. Most lists are majority misses, or “we only needed registered=yes”. Pay for check-exist-by-phone (or ten-at-a-time via batch-check-10) first. Mint userHash only on a hit. Spend at most one second hop, and only on rows a person will see. Do not treat HTTP 200 as “on WhatsApp”, isExist=null as false, or an undetermined check as a cached miss.

It is not KYC or a legal name. A display photo and a public About line are not identity. Per-request cost is on pricing. Process only numbers you are allowed to use, keep the key on the server, and respect WhatsApp’s terms.