Skip to content
BulkNumberChecker

Single WhatsApp Number Lookup API

Check whether one phone number is registered on WhatsApp with a single, synchronous GET request. Authenticate with an API key and the answer comes back in the response body — no , no polling, no CSV. Ideal for one-off lookups, interactive flows, and AI agents.

GET https://api.bulknumberchecker.com/api/v1/lookup?number=%2B6281234567890

When to use this endpoint

The single lookup complements the existing bulk async flow — it does not replace it. Pick the one that matches your job.

Single number — use
  • One GET request, answer in the body.
  • No , no polling loop.
  • Best for interactive lookups and AI agents.
Multiple numbers — use
  • Submit up to 100 numbers per request.
  • Poll for status, then download a CSV.
  • Best for lists. .

Endpoint reference

Request

The query parameter is required. It accepts E.164 format () or a local format (), which is interpreted with a default country of Indonesia (). URL-encode the leading as . Send your API key as or .

curl "https://api.bulknumberchecker.com/api/v1/lookup?number=%2B6281234567890" \
  -H "Authorization: Bearer wac_your_api_key"

Response — 200

{
  "number": "+6281234567890",
  "valid": true,
  "on_whatsapp": true,
  "country_code": "ID",
  "country_name": "Indonesia",
  "cached": true,
  "checked_at": "2026-06-04T07:00:00.000Z"
}

Response fields

FieldDescription
Normalized E.164 number when valid; the trimmed raw input when not.
Whether the input is a parseable phone number (boolean).
true (registered), false (not registered), or null when invalid or undetermined.
ISO 3166-1 alpha-2 code (e.g. ID). null when invalid.
Human-readable country name. null when invalid.
true if served from cache; false if a live WhatsApp query ran.
ISO 8601 timestamp the status was determined; null when invalid.

Code examples

# curl — look up a single number (URL-encode the leading + as %2B)
curl "https://api.bulknumberchecker.com/api/v1/lookup?number=%2B6281234567890"

# Example 200 response:
# {
#   "number": "+6281234567890",
#   "valid": true,
#   "on_whatsapp": true,
#   "country_code": "ID",
#   "country_name": "Indonesia",
#   "cached": true,
#   "checked_at": "2026-06-04T07:00:00.000Z",
#   "rate_limit": { "limit": 5, "remaining": 4, "reset_at": "2026-06-05T00:00:00.000Z" }
# }

Errors

StatusBodyWhen
{"error":"number required"}The number query parameter is missing or empty.
{ valid:false, on_whatsapp:null, ... }The number could not be parsed. No WhatsApp query runs; the credit charged upfront is automatically refunded — invalid input is free.
{"error":"missing_api_key"}No Authorization: Bearer or x-api-key header was sent.
{"error":"invalid_api_key"}The API key is unrecognized or has been revoked.
{"error":"insufficient_credits"}Your credit balance is 0. Top up on /pricing.
{"error":"whatsapp_unavailable"}Cache miss but no WhatsApp session is connected. The charge is automatically refunded; retry later.
{"error":"lookup_timeout"}Cache miss and the live WhatsApp query exceeded the lookup timeout (~6s). The charge is automatically refunded.
Handling 503

A means no live WhatsApp session is currently connected, so a cache-miss lookup cannot run. Cached results still return normally. Retry later, or fall back to the bulk flow.

Auth & credits

  • API key required — send it as or . Create keys on your page.
  • The single lookup shares the same credit balance as and the web app — 1 successful lookup costs 1 credit.
  • 100 free credits to start, then $5 per 1,000. Credits never expire.

Need higher limits? .

Resources

Checking a list instead?

Use the bulk async flow to validate up to 100 numbers per request, poll, and export a CSV.