Number verification API
Create a WhatsApp number verification (API)
Check whether a list of phone numbers is registered on WhatsApp before you message them. Use it to clean imported contact lists, validate sign-up numbers or remove numbers that would only fail.
https://wbiztool.com/api/v1/verification/create/Body: JSON (application/json)
The request creates a verification task and returns a campaign_id straight away. Numbers are then checked in the background by one of your connected WhatsApp numbers. Use the campaign_id with Verification status to follow progress, or with Verification results to read the results.
Quick example#
curl -X POST https://wbiztool.com/api/v1/verification/create/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"campaign_name": "Website leads - September",
"numbers": ["919876543210", "+91 98765 43211", "14155550123"]
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/verification/create/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"campaign_name": "Website leads - September",
"numbers": ["919876543210", "+91 98765 43211", "14155550123"],
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 4xx or 5xx
if result["status"] == "success":
print("Task created, campaign_id", result["campaign_id"])
print("Accepted numbers:", result["numbers_submitted"])
else:
print(f"Failed ({response.status_code}):", result["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/verification/create/", {
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
campaign_name: "Website leads - September",
numbers: ["919876543210", "+91 98765 43211", "14155550123"],
}),
});
const result = await response.json(); // read the body even when the HTTP code is 4xx or 5xx
if (result.status === "success") {
console.log("Task created, campaign_id", result.campaign_id);
console.log("Accepted numbers:", result.numbers_submitted);
} else {
console.error(`Failed (${response.status}):`, result.message);
}<?php
$payload = [
'campaign_name' => 'Website leads - September',
'numbers' => ['919876543210', '+91 98765 43211', '14155550123'],
];
$ch = curl_init('https://wbiztool.com/api/v1/verification/create/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_KEY',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? '') === 'success') {
echo 'Task created, campaign_id ' . $result['campaign_id'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}Replace YOUR_API_KEY with a key from Settings → API keys. The key decides which workspace the task belongs to.
Request parameters#
Header
AuthorizationheaderrequiredBearer YOUR_API_KEY. The key must be active and not deleted. Noclient_idis needed for this API.Content-TypestringrequiredMust be
application/json. With any other content type,numbersisn't read and you getNumbers array is required.
Body
numbersarray of stringsrequiredThe phone numbers to check, each with its country code, for example
919876543210for an Indian number. Before checking, each number is cleaned:- spaces,
+,-and brackets are removed - one leading
0is removed - the result must contain only digits and be at least 10 digits long
Numbers that don't pass are silently left out. Duplicates are not removed, so each copy is checked separately.
- spaces,
campaign_namestringoptionalA name to find the task by in the dashboard. If you leave it out, the name is
API Verificationfollowed by the server's date and time in IST (UTC+5:30), for exampleAPI Verification 20260916_154500. Names can be up to 500 characters. Don't sendnull: longer or null names fail with HTTP500.
Response#
A successful request returns HTTP 200:
{
"status": "success",
"message": "Verification task created successfully",
"campaign_id": 4521,
"numbers_count": 3,
"numbers_submitted": ["919876543210", "919876543211", "14155550123"]
}
| Field | Type | Description |
|---|---|---|
status | string | "success". Errors return "error". |
message | string | Verification task created successfully. |
campaign_id | integer | ID of the verification task. Use it with Verification status and Verification results. |
numbers_count | integer | How many numbers were accepted after cleaning. |
numbers_submitted | array of strings | The cleaned numbers that will be checked. Compare it with what you sent to see which numbers were dropped. |
Every accepted number starts as pending. The task also appears on the Number verification page in your dashboard. Its card there may keep showing Processing after it finishes, so use Verification status for the real state.
Errors#
Errors return a JSON body with status set to "error" and an HTTP error code:
{ "status": "error", "message": "No valid phone numbers found" }
| HTTP | Message | How to fix it |
|---|---|---|
405 | Only POST method allowed | Send a POST request. |
401 | API key required | Add the Authorization: Bearer YOUR_API_KEY header. |
401 | Invalid API key | Check the key exists and hasn't been deleted or disabled. |
403 | Verification feature not available for your plan | Your plan doesn't include number verification. Upgrade your plan. |
400 | Numbers array is required | Send numbers as a non-empty JSON array, with Content-Type: application/json. |
400 | No valid phone numbers found | None of the numbers had 10 or more digits after cleaning. Include the country code. |
400 | Request contains N numbers but your plan allows only M verifications | Your plan limits how many numbers one request can contain. Split the list into smaller requests. |
500 | Internal server error: … | Usually the JSON body isn't valid, for example because of a trailing comma. |
How numbers are checked#
The task is queued
The API stores every accepted number as
pendingand returns immediately.A connected WhatsApp number checks them
Numbers are checked up to 10 at a time using a WhatsApp number connected in WhatsApp settings. Each number becomes
verifiedif it's registered on WhatsApp, orinvalidif it isn't. Checks only run on a connected number that isn't busy sending messages, so during a large campaign they can wait until sending finishes.You read the results
Poll Verification status until
overall_statusiscompleted, then read the numbers from the same response or from Verification results.
Tips#
- Always include the country code. A 10-digit local number without it passes the length check, but it's checked exactly as written, so the result won't be for the number you meant.
- Don't use the
00international prefix. Only one leading0is removed, so00919876543210is checked as0919876543210. Send919876543210. - Remove duplicates yourself before sending, so you don't spend your plan's per-request limit on repeats.
- Check
numbers_submittedto find numbers that were dropped because they were too short or contained letters. - Large lists: if you hit the per-request limit, send several smaller tasks and track each
campaign_id.
New to number verification? See the Number verification guide.
