Install
pip install wavalid-py-sdkRequires Python 3.9+. No dependencies — uses the standard library urllib.
Authentication
Every request needs an API key, created from the wavalid dashboard. Never hardcode it — read it from an environment variable.
import os
from wavalid import WavalidClient
client = WavalidClient(api_key=os.environ["WAVALID_API_KEY"], base_url="https://wavalid.com")base_url is the root domain only — do not append /api or /api/v1, the client adds that path itself.
client.validate(phone_number, batch_id=None)
Validates a single phone number.
result = client.validate("+14155551234")
# result["status"]: "valid" | "invalid" | "limit"client.validate_bulk(phone_numbers, batch_id=None)
Validates up to 100 phone numbers in one request.
bulk = client.validate_bulk(["+14155551234", "+447911123456"])
# bulk["results"], bulk["creditsUsed"], bulk["creditsRemaining"]For more than 100 numbers, split the list into chunks of 100 and call validate_bulk once per chunk.
Errors
Both methods raise wavalid.ApiError on any non-2xx response — always wrap calls in try/except, never assume success.
from wavalid import ApiError
try:
result = client.validate("+14155551234")
except ApiError as error:
if error.code == "rateLimitExceeded":
... # back off and retry later
print(error.status_code, error.code, error.message)| status_code | code | meaning |
|---|---|---|
| 400 | (none) | phone_number is not a valid international number, or phone_numbers is empty/over 100 |
| 401 | (none) | missing or invalid API key |
| 402 | insufficientCredits | account has no credits left |
| 404 | (none) | batch_id does not exist for this account |
| 429 | rateLimitExceeded | too many requests; back off |
| 502 | (none) | upstream WhatsApp check failed; safe to retry |
Full example
import os
from wavalid import WavalidClient, ApiError
client = WavalidClient(api_key=os.environ["WAVALID_API_KEY"], base_url="https://wavalid.com")
try:
result = client.validate("+14155551234")
print(result["status"], result["creditsRemaining"])
bulk = client.validate_bulk(["+14155551234", "+447911123456"])
print(bulk["results"], bulk["creditsUsed"])
except ApiError as error:
print(f"wavalid error {error.status_code}: {error.message}")