cURL 请求
POST /api/v1/bulk-taskscurl -X POST "https://api.carrierlookup.online/api/v1/bulk-tasks" \
-H "X-API-Key: sk_your_api_key" \
-F service_type=number_activity_batch \
-F country=US \
-F [email protected]两步接入：提交文件，再查询任务
提交后立刻返回任务号；之后按任务号查询状态，任务成功时响应里会带上结果文件的下载链接。下面每个请求都配上它自己的响应。
1. 提交文件
立即返回任务号，此时 preparing 为 true，后台正在预处理文件：去掉无效行、重复行，号码任务还会去掉没带国家码和不属于所选国家的号码，这些都不计费。按提交行数冻结余额，完成后按实际用量结算，差额退回。
响应：任务已创建
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "number_activity_batch",
"status": "processing",
"country": "US",
"submitted_lines": 509,
"total": 509,
"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://api.carrierlookup.online/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"响应：任务已完成
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "number_activity_batch",
"status": "success",
"country": "US",
"submitted_lines": 509,
"total": 500,
"invalid_cnt": 3,
"no_code_cnt": 0,
"other_country_cnt": 0,
"duplicate_cnt": 6,
"preparing": false,
"success_cnt": 495,
"failure_cnt": 5,
"result_url": "https://…/result.csv",
"created_at": "2026-09-08T09:30:00Z"
}
}一个批量任务是怎么跑完的
批量不是把实时检测放大 —— 它是一次提交、后台执行、稍后取件。整个过程您不需要守着页面，任务状态和结果都留在后台。
01上传号码文件
一行一个号码的 .txt 或 .csv。文件流式提交，服务器不保存文件副本。
02预检并冻结余额
空文件、格式明显不对、行数不足等问题在上传时直接拒绝；通过后冻结余额，文件进入后台预处理：去除重复行和无效行，并校验国家一致性。预处理不通过的任务会标记为失败并全额退款；通过的只检测剩下的条目，完成后结算。
03后台执行
任务在后台跑，您可以关掉页面。失败会立即反馈并全额退款。
04下载结果文件
完成后在批量检测页下载。只按实际返回结果的号码计费，差额自动退回。
结果文件里有哪些列
下载的是一份 CSV 文件，就是完整的结果表。
结果文件的列
identifier·12345678900— 提交的号码，统一为带国家码的纯数字、不含加号和空格（例如 12345678900），用于把活跃度结果准确写回名单、客户或线索记录。它只承担匹配和追溯作用，不包含用户的活跃时间、频率或互动明细。activated·true— 本项服务返回的活跃判定：true 表示命中，false 表示明确未命中。不提供活跃日期、次数或时间窗口；请结合您自己的互动记录解读，不能推断用户是否会响应。
什么时候该用这一款
活跃度分群
将返回信号写入受众标签，与最近登录、购买或授权状态交叉查看，形成更适合后续复核的分组。
下载后以 identifier 关联原始记录，保留名单来源，方便人工追溯。
关联字段：identifier
用户召回
在安排召回前，根据活跃信号和您已有的互动记录确定优先级；没有返回信号的记录不等于用户永远不会响应。
将明确的 true、false 与缺失结果分别处理；缺失项保留在待复核队列。
分组字段：activated
受众规划
先按信号、地区或客户阶段拆分名单，再为各分组配置不同的内容、频率和触达节奏，并持续观察业务结果。
将本次结果与团队自己记录的任务日期一起保存；需要更新时重新提交任务。
回写字段：identifier · activated
活跃度检测（批量）是什么？
上传同一国家的号码名单，任务完成后下载 identifier 与 activated 两列结果。该信号可辅助受众分组，但不提供观测时间窗口、最后活跃时间或活跃次数，也不能直接把未命中的记录认定为沉默用户。
这款产品的使用限制
- 请按所选产品理解 activated：号码有效性／激活信号或活跃性信号，不包含具体活跃日期或频率。
- 结果不能证明身份或联系许可，也不保证电话可接通或消息可送达。
- 结果不会自动刷新。如需重新检测，请提交新任务。
关于活跃度检测的常见问题
true、false 和没有结果分别代表什么？
true 是本项检测命中，false 是明确未命中；两者都是已获得的判定，不能把 false 当成执行失败或免费项。缺失结果、无法判定与执行失败应结合任务统计和最终结算单独处理，不能自动补为 false。
能判断最近几天活跃或保证送达吗？
不能。当前结果不包含活跃时间窗口、最后活跃日期、频率或互动明细，也不能保证电话接通或消息送达。请将信号与您自己的业务数据和联系许可共同使用。
是否支持实时检测？
本产品仅支持异步文件任务。实时运营商查询不返回号码有效性或活跃性信号。
文件里有无效号码会怎样？
预检阶段会剔除格式不合法的行，它们不计入计费基数。剩下的号码里，上游没能返回结果的那部分也不收费。只对真正拿到结果的号码计价。
任务要跑多久？
取决于号码量与产品类型。提交后可以关掉页面，任务在后台执行，完成后在批量检测页下载结果。
失败了钱会退吗？
会。任务失败全额退款。任务成功但部分号码没出结果，那部分自动退回。提交时冻结的余额与最终实收的差额始终会退。