Quick Start

Get started in 2 minutes

1

Get your API Key

Generate an API key from your dashboard.

2

Make your first request

Use the example below to validate a phone number.

3

Handle the response

Check the status field to determine if the number is valid.

Authentication

Secure your API requests

All API requests require authentication using a Bearer token. Include your API key in the Authorization header.

Header Format

Authorization: Bearer YOUR_API_KEY

Keep your API key secure!

Never expose your API key in client-side code. Always make API calls from your server.

Base URL

API endpoint base

All API requests should be made to:

Base URL

https://wavalidator.com/api/v1/

Validate Number

Check if a phone number has WhatsApp

POST /api/v1/validate/

Request Body

Parameter	Type	Required	Description
phone_number	string	Required	Phone number with country code (e.g., "14155551234")

Example Request Body

{
    "phone_number": "14155551234"
}

Response

Field	Type	Description
phone_number	string	The validated phone number
status	string	"valid" if registered on WhatsApp, "invalid" if not, or "limit" when a rate limit has been reached (HTTP 429)
credits_remaining	integer	Your remaining credit balance

✓ Valid Number (200 OK)

{
    "phone_number": "14155551234",
    "status": "valid",
    "credits_remaining": 99
}

✗ Invalid Number (200 OK)

{
    "phone_number": "14155550000",
    "status": "invalid",
    "credits_remaining": 98
}

Code Examples

Ready-to-use code snippets

Python requests

import requests

url = "https://wavalidator.com/api/v1/validate/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "phone_number": "14155551234"
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result["status"] == "valid":
    print("✓ Number has WhatsApp!")
else:
    print("✗ Number does not have WhatsApp")

JavaScript fetch

const validateNumber = async (phoneNumber) => {
  const response = await fetch('https://wavalidator.com/api/v1/validate/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone_number: phoneNumber
    })
  });
  
  const result = await response.json();
  
  if (result.status === 'valid') {
    console.log('✓ Number has WhatsApp!');
  } else {
    console.log('✗ Number does not have WhatsApp');
  }
  
  return result;
};

// Usage
validateNumber('14155551234');

PHP cURL

<?php

$url = 'https://wavalidator.com/api/v1/validate/';
$api_key = 'YOUR_API_KEY';
$phone_number = '14155551234';

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $api_key,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'phone_number' => $phone_number
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if ($result['status'] === 'valid') {
    echo "✓ Number has WhatsApp!";
} else {
    echo "✗ Number does not have WhatsApp";
}

?>

cURL Terminal

curl -X POST https://wavalidator.com/api/v1/validate/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "14155551234"}'

Bulk Check

Validate up to 100 numbers in one request

Pricing: 1 credit per number

Each number in the payload costs 1 credit. Maximum 100 numbers per request. Only successfully checked numbers consume credits.

POST /api/v1/bulk-check/

Request Body

Parameter	Type	Required	Description
numbers	array[string]	Required	Array of phone numbers with country code. Max 100 items.

Example Request Body

{
    "numbers": [
        "14155551234",
        "14155550000",
        "447911123456"
    ]
}

Response Fields

Field	Type	Description
checked	integer	Number of numbers actually processed
invalid	integer	Numbers skipped due to empty/invalid format
total	integer	Total numbers submitted in payload
credits_used	integer	Credits consumed by this request
credits_remaining	integer	Your remaining credit balance
results	array	Per-number result objects (see below)

Result Object

Field	Type	Description
number	string	The phone number checked
exists	boolean	true if the number has WhatsApp, false otherwise
source	string	Data source used for the check (e.g. "live")

Example Response

✓ 200 OK

{
    "checked": 3,
    "invalid": 0,
    "total": 3,
    "credits_used": 3,
    "credits_remaining": 97,
    "results": [
        {
            "number": "14155551234",
            "exists": true,
            "source": "live"
        },
        {
            "number": "14155550000",
            "exists": false,
            "source": "live"
        },
        {
            "number": "447911123456",
            "exists": true,
            "source": "live"
        }
    ]
}

Code Examples

Python requests

import requests

url = "https://wavalidator.com/api/v1/bulk-check/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "numbers": ["14155551234", "14155550000", "447911123456"]
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

print(f"Checked: {result['checked']} numbers")
for r in result['results']:
    status = "✓ Has WhatsApp" if r['exists'] else "✗ No WhatsApp"
    print(f"{r['number']}: {status}")

JavaScript fetch

const bulkCheck = async (numbers) => {
  const response = await fetch('https://wavalidator.com/api/v1/bulk-check/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ numbers })
  });

  const result = await response.json();
  result.results.forEach(r => {
    console.log(`${r.number}: ${r.exists ? 'Has WhatsApp' : 'No WhatsApp'}`);
  });
  return result;
};

// Usage
bulkCheck(['14155551234', '14155550000', '447911123456']);

PHP cURL

<?php

$url = 'https://wavalidator.com/api/v1/bulk-check/';
$api_key = 'YOUR_API_KEY';
$numbers = ['14155551234', '14155550000', '447911123456'];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $api_key,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode(['numbers' => $numbers])
]);

$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);

foreach ($result['results'] as $r) {
    echo $r['number'] . ": " . ($r['exists'] ? "Has WhatsApp" : "No WhatsApp") . "\n";
}

?>

cURL Terminal

curl -X POST https://wavalidator.com/api/v1/bulk-check/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["14155551234", "14155550000", "447911123456"]}'

Error Handling

Handle errors gracefully

400

Bad Request

Invalid JSON format or missing phone_number parameter.

401

Unauthorized

Missing or invalid API key. Check your Authorization header.

402

Payment Required

You've run out of credits. Purchase more credits to continue.

429

Too Many Requests — "status": "limit"

Rate limit reached (per-minute). The response body carries "status": "limit". Wait before trying again.

500

Internal Server Error

Something went wrong on our end. Please try again later.

API Documentation

Quick Start

Get your API Key

Make your first request

Handle the response

Authentication

Base URL

Validate Number

Request Body

Response

Code Examples

Bulk Check

Request Body

Response Fields

Result Object

Example Response

Code Examples

Error Handling

Bad Request

Unauthorized

Payment Required

Too Many Requests — "status": "limit"

Internal Server Error

Ready to get started?