API Documentation

Three steps to your first result:

1. Create a free account.
2. Make an API key in your dashboard.
3. Send your first request.

Every request needs an API key. There is no way to use the API without one.

Send all requests to this address:

https://api.waverify.app

Add the path to the end. For example, the check endpoint is https://api.waverify.app/api/v1/check.

Always use https. Plain http does not work.

Send your key in a header called X-API-Key:

X-API-Key: wav_live_xxxxxxxxxxxxxxxxxxxxxxxx

You see the full key only once — when you create it. We do not keep a copy, so we cannot show it to you again. Save it somewhere safe straight away.

Keep the key in an environment variable. Do not write it directly in your code, and do not upload it to GitHub. If someone else gets your key, delete it in the dashboard and make a new one.

If you are signed in to the dashboard, your session uses a short-lived Bearer token instead of a key. Both work on the same endpoint. We record which one you used for each request.

POST/api/v1/check

Send one phone number. Write it in international format: a + sign, then the country code, then the number.

Spaces, dashes and brackets are fine — we remove them for you. A number without a country code is rejected. We never guess the country.

What you send

Example request

curl -X POST https://api.waverify.app/api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wav_live_your_api_key" \
  -d '{"phone": "+8801712345678"}'

With an email

The email is extra. It never changes the WhatsApp part of the answer. A bad email does not fail the request either: you still get status 200, with the problem described in email_info. See Email lookup below.

curl -X POST https://api.waverify.app/api/v1/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wav_live_your_api_key" \
  -d '{"phone": "+8801712345678", "email": "someone@example.com"}'

The number is on WhatsApp

{
  "success": true,
  "phone": "+8801712345678",
  "exists": true,
  "display_name": "Acme Store",
  "name_source": "business_verified",
  "about": "Open 9-6, Sat closed",
  "business": true,
  "profile_photo": "https://cdn.waverify.app/p/9f2c.jpg",
  "profile_photo_id": "1721728451",
  "device_count": 2,
  "number_info": {
    "country_code": "+880",
    "region": "BD",
    "location": "Bangladesh",
    "carrier": "Grameenphone",
    "line_type": "mobile",
    "timezones": ["Asia/Dhaka"],
    "international_format": "+880 1712-345678",
    "national_format": "01712-345678"
  },
  "email_info": null,
  "gravatar": null,
  "response_time_ms": 214,
  "cached": false,
  "checked_at": "2026-07-23T10:04:11Z"
}

The number is not on WhatsApp

This is still a successful request. You get status 200 with exists: false, and it uses one request from your monthly total.

{
  "success": true,
  "phone": "+14155552671",
  "exists": false,
  "display_name": null,
  "name_source": null,
  "about": null,
  "business": false,
  "profile_photo": null,
  "profile_photo_id": null,
  "device_count": null,
  "number_info": {
    "country_code": "+1",
    "region": "US",
    "location": "San Francisco, CA",
    "carrier": null,
    "line_type": "fixed_line_or_mobile",
    "timezones": ["America/Los_Angeles"],
    "international_format": "+1 415-555-2671",
    "national_format": "(415) 555-2671"
  },
  "email_info": null,
  "gravatar": null,
  "response_time_ms": 187,
  "cached": false,
  "checked_at": "2026-07-23T10:04:12Z"
}

Fields in the answer

Names, and why they are missing

Business accounts give you a real name. Personal accounts almost never do: WhatsApp does not show a personal name to someone who is not a contact. So display_name is usually null for a normal person.

This is not an error. Do not show it to your users as one. Use name_source to explain what you did get.

about and profile_photo do come back for personal accounts, as long as the person kept the normal privacy setting. They are null if the person hid them.

Profile pictures expire

profile_photo is a WhatsApp link that stops working after a few hours. Do not save the link. If you need the picture, download it and keep your own copy.

To spot a new picture without downloading anything, save profile_photo_id and compare it next time.

Every answer has a number_info object. It comes from the number itself, not from WhatsApp, so it is filled in even when exists is false.

Values for line_type

Send an email and you get two things back: email_info, our verdict on the address itself, and gravatar, the public profile behind it.

Is the email real?

We check two things without ever sending a message: the address is written correctly, and its domain publishes somewhere to deliver mail.

That is as far as anyone can honestly go. The only way to prove one exact mailbox exists is to try to send to it, which gets the sender blocked, so we do not do it. Read deliverable as “this domain accepts mail”, not “this person exists”.

{
  "email": "jane@acme.com",
  "syntax_valid": true,
  "domain": "acme.com",
  "deliverable": true,
  "mx_hosts": ["mx.acme.com"],
  "disposable": false,
  "role_account": false,
  "free_provider": false,
  "status": "valid",
  "reason": null
}

A bad email is not an error

You still get status 200, and the WhatsApp part of the answer is unaffected. The problem is described in email_info instead.

{
  "email": "jane@@acme",
  "syntax_valid": false,
  "domain": "acme",
  "deliverable": null,
  "mx_hosts": [],
  "disposable": false,
  "role_account": false,
  "free_provider": false,
  "status": "invalid_syntax",
  "reason": "The part after the @-sign contains invalid characters: '@'."
}

deliverable has three values

true and false mean what you expect. null means we could not find out — usually the domain lookup timed out.

null is not false. If your code does if (!deliverable) it will call good addresses bad whenever a lookup is slow. Check the three cases separately.

Values for status

disposable wins over valid when both apply. Those addresses do receive mail — that is exactly why they are worth flagging.

Checking an email on its own

If the email is all you have, post it to /check/email. You get the same email_info, plus any Gravatar profile — with no phone number involved.

Two things make this route different. It never contacts WhatsApp, so it keeps working even when a number check cannot. And it does not use up any of your monthly requests — only the per-minute rate limit applies.

curl -X POST https://api.waverify.app/api/v1/check/email \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wav_live_your_api_key" \
  -d '{"email": "someone@example.com"}'

{
  "success": true,
  "email": "jane@acme.com",
  "email_info": {
    "email": "jane@acme.com",
    "syntax_valid": true,
    "domain": "acme.com",
    "deliverable": true,
    "mx_hosts": ["mx.acme.com"],
    "disposable": false,
    "role_account": false,
    "free_provider": false,
    "status": "valid",
    "reason": null
  },
  "gravatar": null,
  "response_time_ms": 96,
  "cached": false,
  "checked_at": "2026-07-29T10:04:11Z"
}

Gravatar profile

We also look the address up on Gravatar and put any public profile in gravatar.

Most emails have no Gravatar profile, so expect null often. It is also null when you sent no email, or when the address was too malformed to look up.

{
  "display_name": "Jane Roe",
  "about": "Product designer.",
  "location": "Dhaka, Bangladesh",
  "job_title": "Designer",
  "company": "Acme",
  "pronouns": null,
  "avatar_url": "https://gravatar.com/avatar/…",
  "profile_url": "https://gravatar.com/janeroe",
  "verified_accounts": [
    { "service": "Twitter", "url": "https://twitter.com/janeroe" },
    { "service": "LinkedIn", "url": "https://linkedin.com/in/janeroe" }
  ]
}

Every field inside can be null — people fill in only what they want to.

Every error looks the same. In your code, check error.code. Do not check the message text — the wording can change, but the code will not.

{
  "success": false,
  "error": {
    "code": "quota_exceeded",
    "message": "You have used all 100 requests included in the Free plan this period.",
    "details": {}
  }
}

List of error codes

There are two separate limits. Please plan for both.

1. Requests per minute

Free: 10. Starter: 60. Pro: 300. Enterprise: your own limit.

If you go over, you get status 429 with the code rate_limit_exceeded. Wait a short time, then send the request again.

2. Requests per month

Each plan includes a number of requests per month. When you use them all, you get status 402 with the code quota_exceeded. You can upgrade your plan at any time.

If you check the same number twice in a short time, the second answer comes from our saved results and is marked cached: true. It is faster, but it still counts towards your monthly total.

This page is the full reference. There is one endpoint, and everything it can return is listed above.

If something does not work the way this page describes, email support@waverify.app. Please include the error.code you received and the time of the request — that is enough for us to find it in our logs.