Reference

WA Lookup API reference

Every endpoint shares one API key and one balance.

Item	Value
Base URL	https://walookup.com
Auth header	X-API-Key: sk_your_api_key
Response envelope	{ code, msg, data }

Prices are not listed here; every product is billed per successful check. See pricing

Authentication

Use an API key created in Settings and send it with every request in the X-API-Key header.

Auth header

X-API-Key: sk_your_api_key

Keep your API key secretAlways call this endpoint from your server. Anyone holding the key can spend your balance.

Synchronous checks

POST/api/v1/checkPOST/api/v1/batch-check

Submit one identifier, or up to 100 in one request, and read the result in the same response. No polling, no callbacks. An undetermined result returns 422 with code 42200 and is not charged. A multi request keeps the input order, bills each identifier independently, and has 300 seconds to finish — if it does not, the whole request fails and every charge is refunded.

Parameters

Field	Type	Description
`service_type`	string	Product code, one of the products listed below.
`identifier`	string	Single check: one phone number in E.164 form, with or without the leading `+`. The server normalizes it.
`identifiers`	string[]	Multi check: 1 to 100 phone numbers. The response preserves this order.

Products in this group

WhatsApp Registration CheckwsConfirm whether a number is registered on WhatsApp — useful for checking a contact list before you send.Product page
WhatsApp Avatar Checkws_avatarCheck whether a number is registered on WhatsApp and return the avatar fields: avatar (whether one was obtained) and avatar_url.Product page
WhatsApp Business Account Checkws_businessCheck registration and identify whether the number uses a WhatsApp Business account.Product page

WhatsApp Registration Check

wsphone

Confirm whether a number is registered on WhatsApp — useful for checking a contact list before you send.

Single check

POST/api/v1/check

Request

curl -X POST "https://walookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws",
    "identifier": "+17253100591",
    "registered": true
  }
}

Response fields

Field	Type	Description
`registered`	boolean	Whether the number is registered on WhatsApp.

Multi check

POST/api/v1/batch-check

Request

curl -X POST "https://walookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Response fields

Field	Type	Description
`exists`	boolean	Whether this number produced a result. false means the format was invalid, the result was undetermined, or the check failed; when false, none of the fields below are present.
`registered`	boolean	Whether the number is `registered`. Present only when `exists` is true, with the same meaning as the single check.

WhatsApp Avatar Check

ws_avatarphone

Check whether a number is registered on WhatsApp and return the avatar fields: avatar (whether one was obtained) and avatar_url.

Single check

POST/api/v1/check

Request

curl -X POST "https://walookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_avatar", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_avatar",
    "identifier": "+17253100591",
    "registered": true,
    "avatar": true,
    "avatar_url": "<image url>"
  }
}

Response fields

Field	Type	Description
`registered`	boolean	Whether the number is registered on WhatsApp.
`avatar`	boolean	Whether the account has an avatar set. avatar_url can still be empty when the image is not available.
`avatar_url`	string	The avatar URL; an empty string when no URL is available.

Multi check

POST/api/v1/batch-check

Request

curl -X POST "https://walookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_avatar", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_avatar",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true,
        "avatar": true,
        "avatar_url": "<image url>"
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false,
        "avatar": false,
        "avatar_url": ""
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Response fields

Field	Type	Description
`exists`	boolean	Whether this number produced a result. false means the format was invalid, the result was undetermined, or the check failed; when false, none of the fields below are present.
`registered`	boolean	Whether the number is `registered`. Present only when `exists` is true, with the same meaning as the single check.
`avatar`	boolean	Whether the account has an avatar set. avatar_url can still be empty when the image is not available.
`avatar_url`	string	The avatar URL; an empty string when no URL is available.

WhatsApp Business Account Check

ws_businessphone

Check registration and identify whether the number uses a WhatsApp Business account.

Single check

POST/api/v1/check

Request

curl -X POST "https://walookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_business", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_business",
    "identifier": "+17253100591",
    "registered": true,
    "business": true
  }
}

Response fields

Field	Type	Description
`registered`	boolean	Whether the number is registered on WhatsApp.
`business`	boolean	Whether the account is a WhatsApp Business account.

Multi check

POST/api/v1/batch-check

Request

curl -X POST "https://walookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_business", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_business",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true,
        "business": true
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false,
        "business": false
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Response fields

Field	Type	Description
`exists`	boolean	Whether this number produced a result. false means the format was invalid, the result was undetermined, or the check failed; when false, none of the fields below are present.
`registered`	boolean	Whether the number is `registered`. Present only when `exists` is true, with the same meaning as the single check.
`business`	boolean	Whether the account is a WhatsApp Business account.

Asynchronous checks

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Upload a file and get a task id straight away, then check that id until it succeeds. The successful response carries result_url, the result download link. Only two actions exist: submit and check. Poll no more often than once every 30 seconds.

Parameters

Field	Type	Description
`service_type`	string	Bulk product code, one of the products listed below.
`country`	string	ISO 3166-1 code such as `US`. Required for number tasks: every number must include its country code and belong to this country (numbers that do not are left out and not charged); it also selects routing. In multipart it must come before `file`.
`file`	file	A `.txt` or `.csv` with one identifier per line, up to `max_file_bytes` (20MB by default).
`Idempotency-Key`	header	Optional, up to 128 characters. Replaying the same key returns the original task instead of creating a second one.

Products in this group

WhatsApp Bulk Registration Checkws_batchUpload a whole file of numbers, find out which ones are registered on WhatsApp, and download the result file when it finishes.Product page
WhatsApp Bulk Avatar Checkws_avatar_batchCheck a whole list for WhatsApp registration and the avatar: whether each registered number has an avatar set, plus the avatar URL.Product page
WhatsApp Bulk Business Checkws_business_batchCheck a whole list for WhatsApp Business accounts: whether each number is on WhatsApp, and whether that account is a WhatsApp Business account.Product page
WhatsApp Bulk Activity Checkws_active_batchRegistration status plus active days — days since the number was last active — so you can tell live numbers from dormant ones across a whole list.Product page

WhatsApp Bulk Registration Check

ws_batchphone1,000–500,000 per task

Upload a whole file of numbers, find out which ones are registered on WhatsApp, and download the result file when it finishes.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_batch \
  -F country=US \
  -F file=@numbers.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591).
`activated`	true	Whether the number is registered on WhatsApp: true or false.

WhatsApp Bulk Avatar Check

ws_avatar_batchphone1,000–500,000 per task

Check a whole list for WhatsApp registration and the avatar: whether each registered number has an avatar set, plus the avatar URL.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_avatar_batch \
  -F country=US \
  -F file=@numbers.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_avatar_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_avatar_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591).
`activated`	true	Whether the number is registered on WhatsApp: true or false. When it is not true, every other column in that row is left empty.
`avatar`	true	Whether the account has an avatar set: true or false. avatar_url can still be empty when the image is not available.
`avatar_url`	https://pps.whatsapp.net/v/example.jpg	The avatar URL; empty when no URL is available.

WhatsApp Bulk Business Check

ws_business_batchphone1,000–500,000 per task

Check a whole list for WhatsApp Business accounts: whether each number is on WhatsApp, and whether that account is a WhatsApp Business account.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_business_batch \
  -F country=US \
  -F file=@numbers.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_business_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_business_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591).
`activated`	true	Whether the number is registered on WhatsApp: true or false. When it is not true, every other column in that row is left empty.
`business`	false	Whether the account is a WhatsApp Business account: true or false.

WhatsApp Bulk Activity Check

ws_active_batchphone1,000–500,000 per task

Registration status plus active days — days since the number was last active — so you can tell live numbers from dormant ones across a whole list.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_active_batch \
  -F country=US \
  -F file=@numbers.txt

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_active_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_active_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591).
`activated`	true	Whether the number is registered on WhatsApp: true or false. When it is not true, every other column in that row is left empty.
`activedays`	9	Days since the number was last active — smaller is more recent.

Balance

GET/api/v1/balance

Read the current account balance in USD micros. Read-only: it creates no check record and charges nothing.

Balance

GET/api/v1/balance

Request

curl "https://walookup.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Concurrency, timeouts, and retry behavior

Checks are synchronous. Use the returned code to decide whether to accept the result or retry.

Field	Description
`5 requests in flight per user`	Single and multi checks share this limit, and a multi request counts as one request no matter how many numbers it carries. On top of that, only one multi check per account runs at a time; a second one is rejected until the first finishes. Hitting either limit returns `code` `42901` immediately with no charge, plus a `Retry-After` header — resubmit once an in-flight request finishes.
`60s single, 300s multi`	Exceeding the time limit returns `code` `50400` with no charge. A multi check that times out fails as a whole — no partial results, and the full amount is refunded.
`A multi check takes up to 100 numbers`	Results preserve submission order and length. One multi check per account runs at a time; submit the next batch once the previous one has returned.

Error codes

Code	Description
`40000`	Unsupported service type or conflicting request fields
`40001`	Invalid JSON body
`40002`	Invalid number
`40100`	Missing or invalid API key
`40200`	Insufficient balance
`42200`	The number could not be determined at this time. No `data` is returned and the request is not charged
`42900`	A usage quota is exhausted, or there are too many unfinished orders
`42901`	All five in-flight request slots are occupied, or a multi check is already running on this account; submit after an in-flight request finishes. The rejected request is not charged and carries a `Retry-After` header
`50303`	The service is at capacity right now; not charged. Wait for the `Retry-After` seconds and resubmit the same request
`50400`	The check did not finish within its timeout and is not charged; retry it. A batch timeout fails the whole batch and refunds the full amount
`50300`	Validation service maintenance