Free WhatsApp Link API for Developers

Generate WhatsApp links, validate usernames and phone numbers, and render QR codes over plain HTTP GET. No API key, no signup, free. All endpoints return JSON (the QR endpoint returns an image), send CORS headers, and are safe to call from browsers.

Endpoints

Base URL: https://whatsusernames.link. All endpoints are GET.

GET /api/v1/username-link?username=joao.silva&key=AB12&text=hello

WhatsApp link + short link from a username (optional key and prefilled text).

GET /api/v1/phone-link?phone=351912345678&text=hello

Official wa.me click-to-chat link from an international phone number.

GET /api/v1/validate/username?username=joao.silva

Check whether a username is structurally valid.

GET /api/v1/validate/key?key=AB12

Check whether a Username Key is valid (4-8 letters/numbers).

GET /api/v1/validate/phone?phone=351912345678

Check whether a phone number is valid for WhatsApp links.

GET /api/v1/qr?username=joao.silva&format=svg&color=25d366

QR code (PNG or SVG) for a username or phone link. Custom size and colors.

GET /api/v1/openapi.json

Machine-readable OpenAPI 3.1 description of this API.

Business Platform API

Base URL: https://whatsusernames.link. These endpoints are POST with a JSON body, for the WhatsApp Business Platform / Cloud API (BSUID, business usernames, contact resolution, webhook normalization). Same CORS, rate limits, and error format as the endpoints above.

POST /api/v1/business/bsuid/validate

Body

{ "bsuid": "US.13491208655302741918" }

Check whether a Business-Scoped User ID (BSUID) is structurally valid.

POST /api/v1/business/bsuid/parse

Body

{ "bsuid": "US.ENT.11815799212886844830" }

Parse a BSUID into its country code, id, and parent-account flag.

POST /api/v1/business/username/validate

Body

{ "username": "joao.silva" }

Check whether a WhatsApp Business Platform username is structurally valid.

POST /api/v1/business/contact/resolve

Body

{ "username": "joao.silva" }

Resolve a contact from exactly one of bsuid, phone, or username into a single unified shape.

POST /api/v1/business/webhook/normalize

Body

{ "entry": [{ "changes": [{ "value": { "messages": [...], "contacts": [...] } }] }] }

Normalize a raw WhatsApp Cloud API webhook payload (messages or status updates) into a consistent event shape.

Examples

curl

curl "https://whatsusernames.link/api/v1/username-link?username=joao.silva"

JavaScript (fetch)

const res = await fetch(
  "https://whatsusernames.link/api/v1/username-link?username=joao.silva"
);
const data = await res.json();
console.log(data.link); // https://wa.me/joao.silva

curl (Business Platform API)

curl -X POST "https://whatsusernames.link/api/v1/business/bsuid/validate" \
  -H "Content-Type: application/json" \
  -d '{"bsuid": "US.13491208655302741918"}'

Rate limits

60 requests per minute per IP for JSON endpoints, 20 per minute for the QR endpoint. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; exceeding the limit returns HTTP 429 with a Retry-After header. Identical requests are served from CDN cache and don't count against the limit.

Errors

Errors are always JSON with a stable machine-readable code: for example a bad username returns HTTP 400 with a body like the one below. Codes never change within v1.

{
  "error": {
    "code": "username_length",
    "message": "Username must be 3-35 characters."
  }
}

About wa.me username links

WhatsApp's username feature is in a phased regional rollout, and wa.me/<username> links may not open a chat for every account yet. The username-link endpoint includes a notice field with the current status. Phone-number links (wa.me/<phone>) are officially documented and work everywhere today.

OpenAPI 3.1 specification
Free WhatsApp Link API for Developers