WA Lookup
接口参考

WA Lookup API 文档

所有端点共用同一个 API Key 与余额。

项目值
Base URLhttps://walookup.com
鉴权头X-API-Key: sk_your_api_key
响应结构{ code, msg, data }

本页不列价格；每款产品按成功检测计费。 查看定价

认证

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

鉴权头
X-API-Key: sk_your_api_key

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

同步检测

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

提交一个标识，或在一次请求里提交最多 100 个，结果都在同一次响应里返回，不需要轮询也不需要回调。无法判定时返回 422 与业务码 42200，且不计费。多号请求保持提交顺序、每个标识独立计费，整批限时 300 秒，超时则整批失败并全额退款。

请求参数

字段类型说明
service_typestring产品码，取下面列出的任一产品。
identifierstring单号检测用：一个 E.164 手机号，带不带前导 + 都可以，服务端会归一化。
identifiersstring[]多号检测用：1~100 个手机号，响应按此顺序返回。

本类产品

WhatsApp 注册检测

ws手机号

确认号码是否已注册 WhatsApp，适合发送前检查联系人名单。

单号检测

POST/api/v1/check
请求
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
  }
}
响应字段
字段类型说明
registeredboolean号码是否已注册 WhatsApp。

多号检测

POST/api/v1/batch-check
请求
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"] }'
响应
{
  "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
      }
    ]
  }
}
响应字段
字段类型说明
existsboolean该号码是否得到了结果。为 false 表示号码格式错误、结果无法判定或本次检测失败；为 false 时，以下字段均不出现。
registeredboolean该号码是否已注册。仅当 exists 为 true 时出现，含义与单号检测一致。

WhatsApp 头像检测

ws_avatar手机号

在确认号码是否注册 WhatsApp 的同时返回头像字段：avatar（是否取到头像）与 avatar_url（头像地址）。

单号检测

POST/api/v1/check
请求
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>"
  }
}
响应字段
字段类型说明
registeredboolean号码是否已注册 WhatsApp。
avatarboolean该账号是否设置了头像；拿不到图片时 avatar_url 仍可能为空。
avatar_urlstring头像地址；没有地址时为空字符串。

多号检测

POST/api/v1/batch-check
请求
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"] }'
响应
{
  "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
      }
    ]
  }
}
响应字段
字段类型说明
existsboolean该号码是否得到了结果。为 false 表示号码格式错误、结果无法判定或本次检测失败；为 false 时，以下字段均不出现。
registeredboolean该号码是否已注册。仅当 exists 为 true 时出现，含义与单号检测一致。
avatarboolean该账号是否设置了头像；拿不到图片时 avatar_url 仍可能为空。
avatar_urlstring头像地址；没有地址时为空字符串。

WhatsApp 商业账号检测

ws_business手机号

在确认 WhatsApp 注册状态的同时识别商业账号标记，帮助区分商业联系人。

单号检测

POST/api/v1/check
请求
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
  }
}
响应字段
字段类型说明
registeredboolean号码是否已注册 WhatsApp。
businessboolean账号是否为 WhatsApp 商业账号。

多号检测

POST/api/v1/batch-check
请求
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"] }'
响应
{
  "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
      }
    ]
  }
}
响应字段
字段类型说明
existsboolean该号码是否得到了结果。为 false 表示号码格式错误、结果无法判定或本次检测失败；为 false 时，以下字段均不出现。
registeredboolean该号码是否已注册。仅当 exists 为 true 时出现，含义与单号检测一致。
businessboolean账号是否为 WhatsApp 商业账号。

异步检测

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

上传文件后立刻拿到任务号，之后按任务号查询；成功的响应里带 result_url 结果下载链接。对外只有提交与查询两个动作，轮询间隔不要短于 30 秒。

请求参数

字段类型说明
service_typestring批量产品码，取下面列出的任一产品。
countrystringISO 3166-1 国家码（如 US）。号码类任务必填：每个号码都要带国家码并属于这个国家（不符合的号码会被排除、不计费），也用它选路。multipart 时必须排在 file 之前。
filefile.txt 或 .csv，每行一个标识，不超过 max_file_bytes（默认 20MB）。
Idempotency-Keyheader可选，≤128 字符。同一个 key 重放返回原任务，不会重复建单。

本类产品

WhatsApp 批量注册检测

ws_batch手机号每任务 1,000–500,000

上传整份号码文件，批量确认哪些号码已注册 WhatsApp，跑完下载结果文件。

提交任务

POST/api/v1/bulk-tasks
请求
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
响应
{
  "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"
  }
}

查询任务

GET/api/v1/bulk-tasks/{id}
请求
curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
响应
{
  "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"
  }
}
结果列
字段示例说明
identifier17253100591提交的号码，统一为带国家码的纯数字，不含加号和空格（例如 17253100591）。
activatedtrue该号码是否已注册 WhatsApp，取值 true 或 false。

WhatsApp 批量头像检测

ws_avatar_batch手机号每任务 1,000–500,000

整份名单批量确认 WhatsApp 注册状态与头像：已注册号码是否设置了头像，以及头像地址。

提交任务

POST/api/v1/bulk-tasks
请求
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
响应
{
  "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"
  }
}

查询任务

GET/api/v1/bulk-tasks/{id}
请求
curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
响应
{
  "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"
  }
}
结果列
字段示例说明
identifier17253100591提交的号码，统一为带国家码的纯数字，不含加号和空格（例如 17253100591）。
activatedtrue该号码是否已注册 WhatsApp，取值 true 或 false。不为 true 时，该行其余列一律留空。
avatartrue账号是否设置了头像，取值 true 或 false。图片不可用时 avatar_url 仍可能为空。
avatar_urlhttps://pps.whatsapp.net/v/example.jpg头像地址；没有可用地址时为空。

WhatsApp 批量商业号检测

ws_business_batch手机号每任务 1,000–500,000

整份名单筛出 WhatsApp Business 账号：每个号码是否在 WhatsApp 上，以及该账号是否是 WhatsApp Business 账号。

提交任务

POST/api/v1/bulk-tasks
请求
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
响应
{
  "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"
  }
}

查询任务

GET/api/v1/bulk-tasks/{id}
请求
curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
响应
{
  "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"
  }
}
结果列
字段示例说明
identifier17253100591提交的号码，统一为带国家码的纯数字，不含加号和空格（例如 17253100591）。
activatedtrue该号码是否已注册 WhatsApp，取值 true 或 false。不为 true 时，该行其余列一律留空。
businessfalse账号是否为 WhatsApp Business 账号，取值 true 或 false。

WhatsApp 批量活跃度检测

ws_active_batch手机号每任务 1,000–500,000

在批量确认注册状态的同时，返回活跃天数（距最近一次活跃的天数），用来区分活号与僵尸号。

提交任务

POST/api/v1/bulk-tasks
请求
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
响应
{
  "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"
  }
}

查询任务

GET/api/v1/bulk-tasks/{id}
请求
curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
响应
{
  "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"
  }
}
结果列
字段示例说明
identifier17253100591提交的号码，统一为带国家码的纯数字，不含加号和空格（例如 17253100591）。
activatedtrue该号码是否已注册 WhatsApp，取值 true 或 false。不为 true 时，该行其余列一律留空。
activedays9距最近一次活跃的天数，数值越小越近期。

余额查询

GET/api/v1/balance

查询账户当前余额（USD micros）。只读接口：不产生检测记录，也不扣费。

余额查询

GET/api/v1/balance
请求
curl "https://walookup.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"
响应
{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

并发、超时与重试方式

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

字段说明
每个用户最多 5 个请求在处理单号检测与多号检测共用这个上限，一次多号请求算一个请求，与号码数量无关。此外每个账号同时只能跑 1 个多号检测，第二个会被拒绝直到前一个结束。达到任一上限都会立即返回业务码 42901 并附带 Retry-After 响应头，不扣费，等已有请求结束后再提交即可。
单号 60 秒，多号 300 秒超过后返回业务码 50400，不计费；多号超时是整批失败，不返回部分结果，已扣费用全额退回。
多号单次最多 100 个号码结果按提交顺序、同等长度返回。每个账号同时只跑 1 个多号检测，上一批返回后再提交下一批。

错误码

业务码说明
40000不支持的 service_type 或字段冲突
40001JSON 请求体无效
40002号码无效
40100缺少或无效的 API Key
40200余额不足
42200暂时无法判定该号码。不返回 data，且本次不计费
42900次数配额已用完，或未完成订单数超限
429015 个在处理的请求名额已满，或该账号已有一个多号检测在跑；已有请求结束后可再次提交，拒绝请求不扣余额，响应带 Retry-After
50303平台此刻处理中的检测已达上限，不扣费；按 Retry-After 的秒数等待后重新提交同一请求
50400本次检测未在超时预算内完成，不计费，可直接重试；批量超时为整批失败并全额退款
50300检测服务维护中