How to Check if a Phone Number Is on WhatsApp (API)

Published August 23, 2026 Β· UpdatedOctober 16, 2026

isExist is the field people mean by on WhatsApp. A 200 from GET https://api.opendata-api.com/api/project/whatsapp/check-exist-by-phone is not that field. Gateway code: 200 is not that field. userHash is a 24-hour ticket you only receive after isExist is true. Treat HTTP success as registered, or treat a ten-number batch as the same boolean as a single check, and a CRM starts writing "not on WhatsApp" for numbers that came back null, for rows the batch never answered, and for calls that never produced a business result at all.

This WhatsApp number checker article is those failure modes: empty, undetermined, HTTP versus business, and single versus a batch of ten. Nobody is messaged. Opening this page or copying an example does not send a lookup. Running a command does, and it spends credits. Keep the authorized platform key on the server: sign in, copy it from the dashboard, read it as OPENDATA_API_KEY. Query URLs carry the key, so do not paste them into tickets, screenshots or source control.

Say which field you mean by on WhatsApp

Three operations answer a family of "is this number on WhatsApp" questions. They do not share one JSON key.

check-exist-by-phone is the single-number record. Pass the full international number as phoneNumber. A leading + is optional; spaces, dashes and a 00 prefix are accepted because the country code is parsed for you. After you unwrap the gateway envelope, the verdict is isExist:

  • true β€” registered. The same object can carry userHash (valid 24 hours) and hasExtra. Those are for a later profile call, not the yes.
  • false β€” not registered. A clean miss. Do not retry it as a timeout.
  • null β€” undetermined. Queue it. Do not store it as unreachable.

If country code and national number already live in separate columns, check-exist-by-cc-phone takes cc and phone and still answers with isExist. check-active is a standalone active flag for the full number, with no userHash. Use it when a sign-up form only needs a fast active-or-not and will not enrich. Do not read isExist out of that response; it is a different operation.

batch-check-10 is not a louder isExist. You pass up to ten full numbers as a comma-separated accounts list. Each row reports exist (on WhatsApp or not) and isBusiness. isBusiness is a segmentation hint. It is not the registration answer, and a personal account with isBusiness false is still on WhatsApp.

HTTP status and gateway status sit above all of those fields. A missing or unauthorized key, a validation error, or a transport failure shows up as HTTP 4xx/5xx or as a gateway code other than 200. There is no WhatsApp verdict in that envelope β€” fix the credential or the request; do not write false. HTTP 2xx with gateway code: 200 means the check was delivered. Only then read isExist, the active flag, or per-row exist. A delivered null is still a business result: undetermined, not a crash. An unwrapped body with no such key, or an empty batch payload, is malformed or empty, not a list of nos.

The numbers below are documented shapes, not guaranteed hits.

# Documented request shape only β€” running it spends credits.
# curl equivalent:
# GET https://api.opendata-api.com/api/project/whatsapp/check-exist-by-phone
#   key=YOUR_API_KEY&phoneNumber=15551234567

Drop obviously broken values before you spend a request. Store one canonical form per contact so duplicates collapse. Registered is not consented: opt-in is a separate requirement, and a positive isExist does not mean you may message the number.

One number, then ten

A live form has one number. Call check-exist-by-phone or check-active and wait for that one verdict. Padding the request with nine dummy rows so you can "use the batch API" turns a missing row into nine fake nos, and it delays the user until a batch you did not need comes back.

A list is the opposite job. batch-check-10 cuts round trips. Split on ten, pass accounts as a comma-separated list, and keep the requested numbers next to the raw result so you can see which inputs never came back. HTTP 200 on the batch is not ten times exist=true. Classify each row on its own exist. A row with no exist, a short result list, or a transport failure for the group is undetermined for those numbers β€” retry the group, do not mark the ten as unregistered. isBusiness can be stored beside the verdict; it must not overwrite it.

Longer lists loop in groups of ten. Deduplicate on the canonical form first so the same number does not burn two credits in two groups. The file-scale retry and resume pattern lives in how to bulk-verify WhatsApp numbers. Do not copy that script here and then treat every non-true as a miss: bulk throughput still has to preserve unknown.

If you already have a userHash from a true isExist and you actually want a photo or About line, stop. That is enrichment, not this check. Leave it for the lookup guide linked below.

A function that does not collapse unknown

The bug that produces the opening failure is almost always truthiness. In Python None is falsy, and so is False:

# Wrong: null, missing, and false all look like "no"
if not payload.get("isExist"):
    mark_unregistered(number)

Classify with identity checks. Unwrap {code, data} until you are looking at the inner record, and refuse to read isExist when the gateway code is not 200. Retry only undetermined single checks. After the cap, leave the row undetermined.

import os
import time

import requests

BASE = "https://api.opendata-api.com/api/project/whatsapp"
KEY = os.environ["OPENDATA_API_KEY"].strip()


def call(operation, **params):
    try:
        response = requests.get(
            f"{BASE}/{operation}",
            params={"key": KEY, **params},
            timeout=30,
        )
    except requests.RequestException:
        raise RuntimeError("Transport failure; inspect redacted logs") from None
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP failure: {response.status_code}")
    try:
        body = response.json()
    except ValueError:
        raise RuntimeError("Expected JSON") from None
    while isinstance(body, dict) and "code" in body and isinstance(
        body.get("data"), (dict, list)
    ):
        if body.get("code") != 200:
            raise RuntimeError("Gateway business failure; inspect redacted diagnostics")
        body = body["data"]
    return body


def classify_flag(value):
    if value is True:
        return "on_whatsapp"
    if value is False:
        return "not_on_whatsapp"
    if value is None:
        return "undetermined"
    return "malformed"


def check_one(number, retries=2):
    last_message = None
    for attempt in range(retries + 1):
        payload = call("check-exist-by-phone", phoneNumber=number)
        if not isinstance(payload, dict):
            return {"number": number, "status": "malformed"}
        status = classify_flag(payload.get("isExist"))
        if status == "on_whatsapp":
            return {
                "number": number,
                "status": status,
                "userHash": payload.get("userHash"),
            }
        if status != "undetermined":
            return {"number": number, "status": status}
        last_message = payload.get("message")
        time.sleep(2 * (attempt + 1))
    return {"number": number, "status": "undetermined", "reason": last_message}


def check_ten(numbers):
    if not 1 <= len(numbers) <= 10:
        raise ValueError("batch-check-10 accepts 1 to 10 numbers")
    payload = call("batch-check-10", accounts=",".join(numbers))
    # Keep requested inputs beside the raw payload; do not invent a miss
    # for a number the batch did not return.
    return {"requested": list(numbers), "result": payload}


# Documented example numbers β€” not guaranteed registrations.
print(check_one("15551234567"))
print(check_ten(["15551234567", "15557654321", "442071234567"]))

Inside a sign-up form, treat undetermined as "could not verify right now": let the person continue, re-check in the background, and never block them on a null. Cache a true or false with a timestamp and re-check on a schedule; people install WhatsApp later, and a null is not a cacheable no. HTTP 401/403 is a key problem, not a timeout β€” sleeping will not turn it into isExist: true.

When to leave this page

Stay here only while the question is "on WhatsApp or not," including how isExist, the active flag and batch exist fail. Cleaning a file of thousands belongs in bulk-verify WhatsApp numbers. Turning a true isExist into avatar, About text, presence or a business profile is the WhatsApp number lookup and profile photo, About and last seen guides. Checking is not sending: that is send WhatsApp messages via API. When the leftover numbers still need another channel, use the lead verification workflow.

Try the operations on the WhatsApp Number Validation page, or read check-exist-by-phone, check-active and batch-check-10. Pricing covers credits once you outgrow the free grant on a new account.