一个批量任务：一个国家，一款产品

NumDetect 是一条异步批量链路。你上传一个号码文件，选定一款产品和一个国家，后台处理完成后取回结构化的结果文件。它不是实时单号查询，也不发消息、不打电话、不与任何账号交互。

大多数人卡住的地方都在最初两分钟——文件形态和任务范围——所以这两件事值得说明白。

任务的边界是一个国家、一款产品

每个任务恰好携带一款产品和一个 ISO 国家/地区代码。这不是一个可以靠"把不同的行混在一起"绕过去的界面限制，它就是工作单元本身。

实际后果是：一份原始导出通常必须先拆开才能用。跨市场收集来的联系人名单，要拆成每个市场一个任务；想用两种方式给同一批号码打分，就是同一批号码跑两个任务。提前按这个规划，比提交时才发现要轻松得多。

文件要求同样是固定的：1,000 到 100,000 个有效号码，TXT 或 CSV，每行一个号码。还有一条值得直接讲清楚、而不是让人自己撞上——这条批量链路不支持中国大陆号码，也没有别的绕行路径。

提交与轮询

POST /api/v1/bulk-tasks 提交任务，GET /api/v1/bulk-tasks/{id} 查询状态。对外状态只有 processing、success、failed 三种，没有可轮询的中间进度百分比。集成就按这三种状态来做，也不要设计一个会向用户承诺完成时间的界面。

每款产品只回答一个很窄的问题

五款产品共用同一种文件格式，纪律也完全相同：每一款返回的都是信号，而信号不等于下游希望它是的那个结论。

号码有效性（Phone Number Validation） 返回一个激活信号。它不保证电话能接通、短信能送达、消息能投递，也不保证存在应用注册；关于号码归谁、对方是否同意被联系，它一个字都没说。

号码活跃度（Number Activity） 是用于排序和分层的活跃信号。它不是在线状态、不是"最后活跃时间"的时间戳、也不是频次测量。把它当成这三者中的任何一个，都是在给数据凭空添加它并不具备的精度。

电商活跃（E-commerce Active） 同样是信号而不是记录。它不是订单、不是交易、不是消费凭证，也不是购买意向的证据。

高价值用户（High-Value Users） 基于高端设备特征与近期网络活动标记"潜在"高价值。它不是收入、资产或身份的证明，不得作为信贷、就业、住房、保险等决策的唯一依据——这些恰恰是一个概率性信号最不适合承担的高影响用途。

全球运营商检测（Global Carrier Detection） 返回运营商信息。它会受携号转网和不同数据源差异的影响，既不是用户身份查询，也不是实时网络状态。

读结果文件时别自己加结论

五款产品共通的规则说起来很简单，但在赶进度时极容易违反：如实报告你收到的信号，让它保持"信号"这个标签，把"这个信号占多大权重"的判断留给它上面那一层显式地做。

一列叫"活跃度评分"的数据，在进入 CRM 的路上被改名成"高意向客户"的那一刻，所有限定条件就都消失了，下游再也没人能把它们找回来。