Reference

API

Base URL https://your-host. JSON in, JSON out, no SDK required.

Demo data. The checker adapter is not connected, so these responses are generated from a hash — not real WhatsApp state. Set CHECKER_URL to go live.

Authentication

Send the key as a bearer token or as X-API-Key. Keys look like bc_live_ + 32 hex chars.

GET /v1/check

Accepts a phone number in E.164 digits or a username.

curl -H "Authorization: Bearer bc_live_…" \
  "https://your-host/v1/check?number=5511999999999"

curl -H "Authorization: Bearer bc_live_…" \
  "https://your-host/v1/check?username=zed"

{
  "input": "@zed",
  "kind": "username",          // number | username
  "number": "5511999999999",   // resolved number, null if it could not be resolved
  "status": "banned",          // banned | not_banned | unknown
  "reason": "spam",
  "ban_time": "2026-09-14T08:12:00.000Z",
  "appeal_time": null,
  "checked_at": "2026-11-11T02:00:11.000Z",
  "cached": false,
  "demo": false
}

POST /v1/check

Batch, capped by plan: {"targets": ["5511…", "@zed"]} → {"results": [ … ]}.

GET /v1/usage

Plan, daily quota, remaining, 90-day history for the calling key.

Statuses

`banned`	the probe confirmed a ban — show reason and dates
`not_banned`	the probe confirmed the number is usable
`unknown`	timeout, upstream error, unroutable username. Never display as clean

Errors

{ "error": { "code": "quota_exceeded", "message": "daily quota 20 reached" } }

`401 invalid_key`	missing, malformed or revoked key
`429 rate_limited`	per-minute burst, see `Retry-After`
`429 quota_exceeded`	daily quota, resets 00:00 UTC
`400 bad_target`	not a number and not a valid-looking username
`400 batch_too_large`	more targets than the plan allows per call