API 文档 API v1

实时检测单个手机号或邮箱，或将名单作为批量任务提交并下载一份结果文件。每个请求都使用 Bearer API 密钥。

认证

在 API 密钥页面创建密钥，然后在你自己的终端中替换下面的占位符。示例只是文本；复制它们不会发送任何内容。

API 地址https://api.numdetect.com

在本地设置密钥

# API origin: https://api.numdetect.com
export NUMDETECT_API_KEY='YOUR_API_KEY'

每个请求都要发送 Authorization: Bearer <key>。JSON 请求还需要 Content-Type: application/json。不需要 Cookie、CSRF 请求头或 Origin 请求头。
密钥可以读取产品、运行单号和批量检测、读取其结果，以及读取你的余额记录。账号设置、密钥和充值只能在已登录的控制台中管理。
你最多可以创建 10 个密钥，例如每个系统一个，并可随时删除其中任何一个。

请把密钥保存在服务器环境中。不要把密钥放进 URL、截图、共享日志或提交到代码库的源文件。

产品

选择产品 ID 之前，先读取当前产品目录。响应列出所有在售产品，以及它们的输入类型、价格、批量最低数量和支持的国家。

列出产品

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/products" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

single 和 bulk 表示该产品当前是否可用于对应类型的检测。countries 为 ["*"] 表示所有国家，也可以是国家代码列表，邮箱产品则为空。价格为每次检测的 USD micros。

单号检测

POST /api/v1/checks 接收一个手机号或一个邮箱地址，以及一组产品 ID。请求会等待所有产品给出答复（最长约 45 秒），然后返回完成的检测。

检测手机号

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+12025550147","products":["whatsapp","telegram"]}'

检测邮箱地址

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","products":["apple_email","spotify_email"]}'

手机号请带上 + 国家代码。对于没有国家代码的号码，请在请求中添加 "country": "GB"（ISO 国家代码）。

200 · Check

响应就是这次检测：id、规范化后的输入、其国家、charged，以及每个产品在 results 中的一项。每个结果包含 status、result（status 为 success 时为 true 或 false）和 info（部分产品返回的附加字段）。

success

明确结论：result 为 true（已注册）或 false（未注册）。只有这些会收费。

unknown

该产品无法判断。result 为 null，不收费；切勿把它当作 false。

failed

无法访问该产品。result 为 null，不收费；可以稍后重新检测。

读取一次检测

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks/$CHECK_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

列出最近的检测

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

批量检测

POST /api/v1/bulk-jobs 以 multipart 表单数据上传文件。文件会拆分为每个国家一份名单，每个国家由你选择的每个产品分别检测。

提交批量任务

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "[email protected]" \
  -F "products=whatsapp,telegram" \
  -F "input_kind=phone" \
  -F "max_cost=50000000" \
  -F "column=0" \
  -F "header=true"

file：UTF-8 编码的 CSV 或纯文本，最大 100 MB、1,000,000 行。其他列会保留，并在结果文件中返回。
input_kind 为 phone 或 email。column 是号码所在列的序号，从 0 开始（默认 0）；header=true 会跳过第一行。
country（可选）用于没有国家代码的手机号。以 + 或 00 开头的号码保留其自身所属国家。
max_cost 是你最多愿意支付的金额，单位为 USD micros。如果任务费用更高或余额不足，任务会被拒绝，且不会扣费。

200 · BulkJob

响应是该任务，状态为 running，附带行数统计（total、valid、duplicate、invalid）、预留金额，以及每个国家和产品对应的一个子任务。请保留 id 作为你的 JOB_ID。

批量状态与结果

持续读取该任务，直到 status 变为 completed、failed 或 cancelled。较大的名单可能需要一段时间，因此请每隔一两分钟轮询一次，或使用 Webhook。

读取批量任务

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

列出最近的批量任务

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

下载结果文件

当 result_ready 为 true 时，GET /result 会返回一个有效期 10 分钟的下载链接。该链接本身不需要密钥。需要再次下载时，请重新获取新的链接。

获取链接，然后下载

url=$(curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/result" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" | jq -r .url)
curl --fail --silent --show-error --output result.csv "$url"

result.csv 按原始顺序保留每一原始行，并增加 numdetect_status（valid、duplicate 或 invalid）、numdetect_country，以及每个产品一列，取值为 yes、no、unknown、unsupported、failed 或 cancelled。

取消运行中的任务

尚未检测的国家会停止，其预留金额退回你的余额。

取消批量任务

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Webhook

在账号设置页面设置 Webhook URL，即可在批量任务完成时收到通知。每个完成的任务，我们会发送一次 HTTPS POST：

请求体

{
  "type": "bulk_job.finished",
  "data": {
    "id": "10000000-0000-4000-8000-000000000003",
    "status": "completed",
    "total_rows": 1000,
    "valid_rows": 982,
    "charged": 245500,
    "completed_at": "2026-11-11T08:30:00Z"
  }
}

每个请求都带有 webhook-id、webhook-timestamp 和 webhook-signature 请求头。签名为 v1，后接 "<webhook-id>.<webhook-timestamp>.<body>" 的 Base64 HMAC-SHA256，使用你的签名密钥（whsec_…，前缀之后为 Base64）。信任请求体之前，请先比对签名。

请返回任意 2xx 状态码。投递失败会重试几次，每次间隔几分钟。请把 webhook-id 视为唯一标识，因为重试的投递可能会到达两次。

费用与余额

单号检测对每个得到明确结论的产品按其价格收费。无法判断和失败的结果免费。

批量任务在提交时预留其费用：对每个国家和产品，为 max(有效号码数, 该产品的批量最低数量) × 批量价。完成的名单按整笔扣费，含无法判断的行。失败或被取消的名单，其金额退回你的余额。重复行、无效行以及产品不支持的国家均免费。

金额为整数 USD micros：1 USD = 1,000,000 micros。

读取余额记录

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/balance-logs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

POST /checks 和 POST /bulk-jobs 需要 Idempotency-Key 请求头（最长 128 个字符）。每个新请求使用一个新的键。如果响应丢失，请用同一个键再次发送同样的请求：你会得到第一次的结果，而不会被二次扣费。

价格表

错误

错误使用 {error: {code, message, request_id}} 格式。请匹配稳定的 code 而不是 message，联系客服时请附上 request_id。

常见 API 错误
HTTP	错误码	处理方式
400	`invalid_request`	检查各字段、JSON 或表单语法以及输入格式。
401	`unauthorized`	检查密钥是否已提供且尚未被删除。
403	`forbidden`	此操作只能在已登录的控制台中进行，或账号已被停用。
404	`not_found`	检查 ID；只能读取你自己的检测和任务。
409	`conflict`	该 Idempotency-Key 已用于另一个不同的请求。新请求请使用新的键。
409	`insufficient_balance / max_cost_exceeded`	请充值余额，或者如果你接受更高的费用，请调高 max_cost。
409	`product_not_supported`	读取产品目录：该产品已下架，或不接受此类输入。
429	`rate_limited`	请放慢速度，稍后再试。
503	`unavailable / dependency_unavailable`	检测暂时不可用。请稍后再试；未产生任何扣费。

获取你的 API 密钥批量检测 Webhook 设置计费

返回认证