Skip to content
Wbiztool

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.

POSThttps://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"]
  }'

Replace YOUR_API_KEY with a key from Settings → API keys. The key decides which workspace the task belongs to.

Request parameters#

Header

Authorizationheaderrequired

Bearer YOUR_API_KEY. The key must be active and not deleted. No client_id is needed for this API.

Content-Typestringrequired

Must be application/json. With any other content type, numbers isn't read and you get Numbers array is required.

Body

numbersarray of stringsrequired

The phone numbers to check, each with its country code, for example 919876543210 for an Indian number. Before checking, each number is cleaned:

  • spaces, +, - and brackets are removed
  • one leading 0 is 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.

campaign_namestringoptional

A name to find the task by in the dashboard. If you leave it out, the name is API Verification followed by the server's date and time in IST (UTC+5:30), for example API Verification 20260916_154500. Names can be up to 500 characters. Don't send null: longer or null names fail with HTTP 500.

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"]
}
FieldTypeDescription
statusstring"success". Errors return "error".
messagestringVerification task created successfully.
campaign_idintegerID of the verification task. Use it with Verification status and Verification results.
numbers_countintegerHow many numbers were accepted after cleaning.
numbers_submittedarray of stringsThe 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" }
HTTPMessageHow to fix it
405Only POST method allowedSend a POST request.
401API key requiredAdd the Authorization: Bearer YOUR_API_KEY header.
401Invalid API keyCheck the key exists and hasn't been deleted or disabled.
403Verification feature not available for your planYour plan doesn't include number verification. Upgrade your plan.
400Numbers array is requiredSend numbers as a non-empty JSON array, with Content-Type: application/json.
400No valid phone numbers foundNone of the numbers had 10 or more digits after cleaning. Include the country code.
400Request contains N numbers but your plan allows only M verificationsYour plan limits how many numbers one request can contain. Split the list into smaller requests.
500Internal server error: …Usually the JSON body isn't valid, for example because of a trailing comma.

How numbers are checked#

  1. The task is queued

    The API stores every accepted number as pending and returns immediately.

  2. 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 verified if it's registered on WhatsApp, or invalid if 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.

  3. You read the results

    Poll Verification status until overall_status is completed, 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 00 international prefix. Only one leading 0 is removed, so 00919876543210 is checked as 0919876543210. Send 919876543210.
  • Remove duplicates yourself before sending, so you don't spend your plan's per-request limit on repeats.
  • Check numbers_submitted to 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.