WA Lookup

接口约定

两步接入：提交文件，再查询任务

查看完整 API 文档 打开 API Key 页面

提交后立刻返回任务号；之后按任务号查询状态，任务成功时响应里会带上结果文件的下载链接。下面每个请求都配上它自己的响应。

1. 提交文件

立即返回任务号，此时 preparing 为 true，后台正在预处理文件：去掉无效行、重复行，号码任务还会去掉没带国家码和不属于所选国家的号码，这些都不计费。按提交行数冻结余额，完成后按实际用量结算，差额退回。

cURL 请求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
响应：任务已创建200 OK
{
  "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"
  }
}

2. 查询任务

按任务号轮询。预处理完成后恒有 submitted_lines = total + invalid_cnt + no_code_cnt + other_country_cnt + duplicate_cnt，其中 total 是实际检测并计费的条数。任务成功时响应里带成功/失败计数和结果文件下载链接；预处理阶段被拒的任务为 failed，带 reason_detail，并全额退款。

cURL 请求GET /api/v1/bulk-tasks/{id}
curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
响应：任务已完成200 OK
{
  "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"
  }
}

执行方式

一个批量任务是怎么跑完的

批量不是把实时检测放大 —— 它是一次提交、后台执行、稍后取件。整个过程您不需要守着页面，任务状态和结果都留在后台。

  1. 01上传号码文件

    一行一个号码的 .txt 或 .csv。文件流式提交，服务器不保存文件副本。

  2. 02预检并冻结余额

    空文件、格式明显不对、行数不足等问题在上传时直接拒绝；通过后冻结余额，文件进入后台预处理：去除重复行和无效行，并校验国家一致性。预处理不通过的任务会标记为失败并全额退款；通过的只检测剩下的条目，完成后结算。

  3. 03后台执行

    任务在后台跑，您可以关掉页面。失败会立即反馈并全额退款。

  4. 04下载结果文件

    完成后在批量检测页下载。只按实际返回结果的号码计费，差额自动退回。

适用判断

什么时候用批量，什么时候实时更合适

实时检测批量检测
号码数量单号 1 个；多号一次可提交多个，具体上限见 API 文档一次跑完整份大名单——当前数量区间见价格页
拿到结果当场出结果：单号与 API 多号在同一次响应里，网页多号逐个返回任务跑完后下载结果文件
国家/地区不限，一次可以混着查提交时选定一个国家/地区，名单应基本属于它；混入太多别国号码任务会失败并全额退款
结果形态JSON，逐号字段结果文件（一份 CSV，含完整结果表）
典型用途表单校验、客服复核、发送前实时拦截名单清洗、投放前筛选、存量数据治理

实时检测 · 查看价格

产品常见问题

关于商业号检测的常见问题

什么时候用批量，什么时候用实时检测？

整份大名单用批量。号码不多时用实时检测：同一次请求就出结果，不需要等任务调度。

文件里有无效号码会怎样？

预检阶段会剔除格式不合法的行，它们不计入计费基数。剩下的号码里，上游没能返回结果的那部分也不收费。只对真正拿到结果的号码计价。

任务要跑多久？

取决于号码量与产品类型。提交后可以关掉页面，任务在后台执行，完成后在批量检测页下载结果。

失败了钱会退吗？

会。任务失败全额退款。任务成功但部分号码没出结果，那部分自动退回。提交时冻结的余额与最终实收的差额始终会退。

相关产品

其他批量产品

WhatsApp 批量注册检测上传整份号码文件，批量确认哪些号码已注册 WhatsApp，跑完下载结果文件。WhatsApp 批量头像检测整份名单批量确认 WhatsApp 注册状态与头像：已注册号码是否设置了头像，以及头像地址。WhatsApp 批量活跃度检测在批量确认注册状态的同时，返回活跃天数（距最近一次活跃的天数），用来区分活号与僵尸号。