WA Lookup
API 速览单号、批量和余额接口共用 API Key 契约，并统一使用 code / msg / data 响应结构。

快速接入

  1. 1.在设置中创建 API Key。
  2. 2.先通过 GET /api/v1/balance 查询当前余额，再决定是否提交批量请求。
  3. 3.向 /api/v1/check 提交一个号码，或向 /api/v1/batch-check 一次提交最多 100 个号码。
  4. 4.读取 data.registered 和产品特有返回字段。

认证

使用在设置中创建的 API Key，并随每次请求一起发送。

X-API-Key: sk_your_api_key
妥善保管你的 API Key
请始终从你的服务端发起请求；持有该 Key 的任何人都可以消耗你的账户余额。

产品与返回字段

wsWhatsApp 注册检测通过同步 API 或网页后台确认手机号是否已注册 WhatsApp，适合发送前检查联系人名单。ws_avatarWhatsApp 头像检测在确认注册状态的同时，检测该 WhatsApp 账号是否设置头像，并在可获取时返回头像地址。ws_businessWhatsApp 商业账号检测在确认 WhatsApp 注册状态的同时识别商业账号标记，帮助区分商业联系人。
ws

WhatsApp 注册检测

通过同步 API 或网页后台确认手机号是否已注册 WhatsApp，适合发送前检查联系人名单。

01

单号检测

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": "+14155552671" }'
已注册
{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws",
    "identifier": "+14155552671",
    "registered": true
  }
}
未注册
{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws",
    "identifier": "+14155550000",
    "registered": false
  }
}
registeredboolean号码是否已注册 WhatsApp。
02

批量

计费：按号码计算

请求中的每个号码独立计费。单次最多提交 100 个号码；只有成功完成检测的号码才会消耗余额。如果余额不足以覆盖整批号码的最高可能费用，请求会在处理前直接拒绝。

一次请求最多提交 100 个号码，结果按提交顺序返回。

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": ["+14155552671", "+14155550000"] }'
{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "identifier": "+14155552671",
        "exists": true,
        "registered": true
      },
      {
        "identifier": "+14155550000",
        "exists": false
      }
    ]
  }
}
existsboolean该号码是否得到了结果。为 false 表示未能判定——号码格式错误、结果不可判定，或触发了临时限流；为 false 时，以下字段均不出现。
registeredboolean该号码是否已注册。仅当 exists 为 true 时出现，含义与单号检测一致。

限速、并发与重试方式

检测采用同步响应。请根据返回码决定接收结果、降低请求速度，或稍后重试。

  • 每分钟 200 次请求每个用户的控制台与 API 检测共用一个 UTC 固定分钟窗口。业务码 42900 的 Retry-After 表示距下一窗口的秒数。
  • 最多 5 个并发检测每个用户最多同时执行 5 个检测（批量请求内部的号码也共用这个额度）。业务码 42901 表示并发名额已满；已有请求完成后即可再次提交。
  • 429 不扣余额速率或并发限制都在扣费前拒绝，不产生检测结果，也不扣用户余额；调用方可在窗口或并发名额恢复后自行再次提交。
  • 遇到 503 时稍后重试临时服务异常不代表号码检测结果。请保留待处理状态，稍后重试。

错误码

40000不支持的 service_type 或字段冲突
40001JSON 请求体无效
40002手机号无效
40100缺少或无效的 API Key
40200余额不足
42200上游无法判定该号码。不返回 data，且本次不计费
42900超出速率限制
42901并发名额已满；已有请求结束后可再次提交，拒绝请求不扣余额
50300检测服务维护中

准备好开始接入了吗？

准备好了吗？免费注册即可在几秒内获取 API Key。

创建免费账号